# M-Files gRPC API: Vault API
All pages of the Vault API of the M-Files gRPC API 26.11: the book page, then each service followed by its methods. Pages are separated by `---` lines.
---
# Vault API
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/vault/
Everything an application does in a vault on behalf of a user.
39 services, 380 methods, grouped by importance level. Each service page lists its highlighted methods first, then all others.
## Core services
The main developer journeys: documented in the most depth.
| Service | Methods | Summary |
|---|---|---|
| [Server version](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/index.md) `IRPCQueryVersion` | 2 | An interface for querying server version information. |
| [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `IRPCLogin` | 25 | An interface for handling client login & logout operations. |
| [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md) `IRPCVaults` | 3 | An interface for enumerating vaults. |
| [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `IRPCVault` | 26 | An interface for vault-level information and operations. |
| [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md) `IRPCObjectTypes` | 3 | An interface for reading object types. |
| [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md) `IRPCPropertyDefs` | 4 | An interface for retrieving property definitions. |
| [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `IRPCValueLists` | 17 | Reads value lists and their items, and lets users add and edit value list items and traditional folders. |
| [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `IRPCSearch` | 14 | An interface for performing searches. |
| [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `IRPCObjectOperations` | 132 | An interface for handling documents and files |
## Standard services
The rest of the end-user API.
| Service | Methods | Summary |
|---|---|---|
| [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md) `IRPCFileTransfer` | 3 | Stateless file upload. No method requires a sticky session. |
| [Streaming file upload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md) `IRPCFileTransferStreaming` | 2 | File transfer methods that stream the file data. |
| [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `IRPCViews` | 14 | Reads and maintains the views of the vault: the common views and the calling user's own (private) views. |
| [Server push](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/index.md) `IRPCServerDataPush` | 2 | A server-to-client channel: the server pushes requests and notifications to a logged-in client over a long-lived stream. |
| [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md) `IRPCNotificationRules` | 4 | Manages notification rules: which events on which objects send the user a notification. |
| [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `IRPCSharedLinks` | 15 | Creates and manages shared links to files for people outside the vault. |
| [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `IRPCSharedLinksPublic` | 7 | Opens and downloads files through shared links, without logging in. |
| [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `IRPCEvents` | 7 | Reads and sets the user's notification switch, checks whether a user can receive notifications, and sends requests and custom notifications to users. |
| [Event log](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/index.md) `IRPCEventLog` | 1 | Writes custom entries to the vault's event log. |
| [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md) `IRPCThumbnails` | 2 | Gets thumbnail images of document files and the vault's thumbnail settings. |
| [Languages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/index.md) `IRPCLanguages` | 2 | Lists the vault's metadata languages and changes the calling user's vault language. |
| [Named access control lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/index.md) `IRPCNamedACLs` | 1 | Lists the named access control lists that the calling user can see. |
| [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md) `IRPCNamedValueStorage` | 3 | Reads and writes named values: small key-value settings stored in the vault, grouped by storage type and namespace. |
| [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md) `IRPCWorkspace` | 3 | Workspace tabs: the views of related objects shown for an object of a given type. |
| [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md) `IRPCTaskPaneConfigurations` | 4 | Stores the task pane configuration of M-Files Desktop per user and for all users. |
| [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `IRPCFolderUISettings` | 7 | Stores the display settings of folders per user and as common defaults. |
| [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md) `IRPCSubstituteUsers` | 4 | Reads and sets the substitute users of users. |
| [Electronic signatures](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/index.md) `IRPCElectronicSignatures` | 2 | An interface for working with electronic signatures. |
| [Sensitivity labels](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/index.md) `IRPCSensitivityLabels` | 1 | Reads the Microsoft Purview sensitivity labels of files. |
| [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `IRPCExportedDataSets` | 7 | Reads the exported data sets of the vault and reports their export status (M-Files Reporting). |
| [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md) `IRPCDataExport` | 5 | Reads objects, value list items and property value history in bulk, in batches ordered by ID, for exporting vault data to another system. |
| [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `IRPCScanningAndOCR` | 8 | Runs server-side OCR: converts files to searchable PDF and recognizes text in page areas. |
| [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md) `IRPCVaultExtensionMethods` | 5 | Calls vault extension methods: server-side code in the vault that takes a string and returns a string. |
| [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `IRPCClientScript` | 16 | Lists, installs, enables, disables, licenses and removes the applications of the vault: vault applications (server side) and UI extension applications (client side), and downloads their packages and files. |
| [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `IRPCConversationOperations` | 6 | Stores conversations with Aino and their chat turns in the vault, per user. |
| [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md) `IRPCAgent` | 3 | Connects M-Files clients to the Aino agents of M-Files Cloud. |
| [Anonymous login](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/index.md) `IRPCAnonymousLoginOperations` | 2 | An interface for managing anonymous authentication operations. |
| [Identities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/index.md) `IRPCIdentityOperations` | 1 | Lets M-Files cloud services that hand out object and value list item IDs on behalf of a vault ask the vault to replenish their ID ranges. |
| [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `IRPCExtensionAuthentications` | 8 | Manages the credentials that the vault uses to access external systems, such as external repositories connected to the vault, on behalf of the user. |
| [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `IRPCTest` | 9 | An interface for testing connection between a client and the server. |
---
# Server version (IRPCQueryVersion)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/
An interface for querying server version information.
This interface provides a method for querying server version information. This is used to
check the compatibility of the server and client.
Also methods for querying information about the versions
of other M-Files components can be placed here.
- **gRPC service:** `MFiles.IRPCQueryVersion`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCQueryVersion.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCQueryVersion.proto)
## Overview
The only service you can call before anything else: it needs no session and no login, so it is the
standard "is the server there, and which version is it?" probe.
- [QueryVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md) returns the server version. Call it
first to check connectivity and to decide which methods and fields you can rely on.
- [GetUIVersionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/GetUIVersionInfo/index.md) is used by M-Files clients
to find the web UI assets to load; applications rarely need it.
Typical order: `QueryVersion`, then
[GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md) for optional features, then
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md). See
[Connecting to the server](https://developer.m-files.com/APIs/gRPC-API/runtime/connecting/index.md) and
[Versions and compatibility](https://developer.m-files.com/APIs/gRPC-API/runtime/versioning/index.md).
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [QueryVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md) | Gets the server version and the oldest client version the server accepts. | `read` `no session` `idempotent` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [GetUIVersionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/GetUIVersionInfo/index.md) | Gets the version of the web UI assets that M-Files clients should load, and where to load them from. | `read` `no session` `idempotent` |
---
# IRPCQueryVersion.QueryVersion
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Server version](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/
Badges: `Vault API / core` `read` `no session` `idempotent`
Gets the server version and the oldest client version the server accepts.
- **Service:** [Server version](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/index.md) `MFiles.IRPCQueryVersion`
- **gRPC method:** `/MFiles.IRPCQueryVersion/QueryVersion`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/query-version`
- **Request:** [`QueryVersionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md#request)
- **Response:** [`QueryVersionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session and no `mfiles-session-id-bin` header. The response is the same for every caller,
so the result can be cached for the lifetime of the connection.
All four fields are 64-bit packed versions: `major << 48 | minor << 32 | build << 16 | patch`.
For example `7318397729964032` is 26.11.16645.0. Unpack them with shifts, not by formatting the
decimal number.
Over gRPC all three "oldest compatible" fields carry the same value: the oldest client version the
gRPC interface supports.
## Request: QueryVersionRequest
No fields.
## Response: QueryVersionResponse
> Nested 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_version` | `uint64` | The server version, packed as `major << 48 \| minor << 32 \| build << 16 \| patch`. |
| `oldest_compatible_client_version` | `uint64` | The oldest client version that the server accepts over gRPC, packed like `server_version`. |
| `oldest_compatible_admin_client_version` | `uint64` | The oldest admin client version that the server accepts, packed like `server_version`. Over gRPC this equals `oldest_compatible_client_version`. |
| `oldest_compatible_replica_server_version` | `uint64` | The oldest replica server version that the server accepts, packed like `server_version`. Over gRPC this equals `oldest_compatible_client_version`. |
---
# IRPCQueryVersion.GetUIVersionInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Server version](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/GetUIVersionInfo/
Badges: `Vault API / core` `read` `no session` `idempotent`
Gets the version of the web UI assets that M-Files clients should load, and where to load them from.
- **Service:** [Server version](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/index.md) `MFiles.IRPCQueryVersion`
- **gRPC method:** `/MFiles.IRPCQueryVersion/GetUIVersionInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-uiversion-info`
- **Request:** [`GetUIVersionInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/GetUIVersionInfo/index.md#request)
- **Response:** [`GetUIVersionInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/GetUIVersionInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to update their UI; applications rarely need it. Needs no session.
When the server has no UI delivery point configured (the normal case on premises), the call
succeeds with all fields empty. `desktop_version` is never filled in by the server.
## Request: GetUIVersionInfoRequest
No fields.
## Response: GetUIVersionInfoResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `delivery_point_url` | `string` | Delivery Point from which to download UI assets. |
| `ui_version` | `string` | The version of the UI assets currently in use. |
| `available_ui_version` | `string` | The latest available version for this Vault. Empty when not known. |
| `desktop_version` | `string` | The version of M-Files Desktop installed on the machine. Undefined in Web. |
---
# Login and sessions (IRPCLogin)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/
An interface for handling client login & logout operations.
Use this interface to log in to MFServer and to maintain the login session.
- **gRPC service:** `MFiles.IRPCLogin`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 25
- **Proto file:** [`mfiles/IRPCLogin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCLogin.proto)
## Overview
Opens, maintains and closes sessions. Almost every other call needs the session ID that
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) returns, sent as the binary metadata header
`mfiles-session-id-bin` (the 48 bytes of `session_data.session_id`, unchanged).
Which methods matter:
| Job | Methods |
|---|---|
| Find out how to authenticate | `GetServerCapabilities`, `GetAuthenticationConfiguration` |
| Open a session | `LogIn` (vault or server level), `LogInWithSession` (another vault, same user) |
| Keep it open | `KeepAlive`, at least every `session_data.keep_alive_interval_in_seconds` |
| Close it | `LogOut` |
| Inspect it | `GetVaultSessionInfo` |
Typical order:
1. [QueryVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md) and
[GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md) (no session needed).
2. [GetAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md) when
the vault may use single sign-on; `AUTH_METHOD_PLUGIN` means log in with
`AUTH_DATA_TYPE_PLUGIN`, otherwise use user name and password (`AUTH_DATA_TYPE_CREDENTIALS`).
3. [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) with the vault GUID. Keep `session_data`.
4. Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) on a timer while the session is in use.
5. On `UNAUTHENTICATED`, log in again with `LogIn` and continue with the new session ID.
6. [LogOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/index.md) when done. A session that is not logged out holds
its license until it times out.
A session is bound to one vault, or to no vault (a server-level session, opened with the vault
GUID `{00000000-0000-0000-0000-000000000000}`). Methods that need a vault fail with
`E_MFILES_LOGIN_REQUIRED` when called with a server-level session.
Errors: an invalid, expired or missing session is reported as gRPC status `UNAUTHENTICATED` with
no error trailers. All other failures, including a wrong password, use status `UNKNOWN` with the
M-Files error stack in the `mfiles-error-serialized-bin` trailer.
Other methods of this service serve M-Files' own clients (licensing warnings, password
encryption, client settings, replication) and are marked as such.
Guides: [Authentication and sessions](https://developer.m-files.com/APIs/gRPC-API/runtime/authentication/index.md)
covers every login type and the session lifecycle, and
[Call metadata](https://developer.m-files.com/APIs/gRPC-API/runtime/call-metadata/index.md) the headers
that every call sends.
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md) | Gets the features the server supports, without logging in. | `session` `no session` `idempotent` |
| [GetAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md) | Tells a client, before login, whether to authenticate with an authentication plug-in (single sign-on) and returns the plug-in's client-side configuration. | `session` `no session` `idempotent` |
| [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) | Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros. | `session` `no session` |
| [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md) | Opens a new session to a vault (or the server) for the user of an existing session, without authenticating again. | `session` `session` |
| [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) | Tells the server that the session is still in use, so that it does not expire. | `session` `session` `idempotent` |
| [LogOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/index.md) | Ends the session and releases its license. | `session` `session` |
| [GetVaultSessionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/index.md) | Gets basic information about the current vault session: server version and ID, vault GUID and name, and the state of the server push channel. | `session` `session` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [ChangePassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ChangePassword/index.md) | Changes the M-Files password of the logged-in account. | `session` `session` |
| [CreateUserSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/CreateUserSession/index.md) | Opens a session that acts as another user of the vault. | `session` `session` `idempotent` |
| [DisconnectDevice](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md) | Removes a device registration (device token) of the logged-in user in the session's vault. | `session` `session` |
| [GetAuthenticationPlugins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationPlugins/index.md) | Lists the authentication plug-ins installed on the server, without their configurations. | `session` `no session` |
| [GetClientSettingsByType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetClientSettingsByType/index.md) | Gets client settings (theme, timeouts, banners, web security settings) for an M-Files web, desktop or Outlook client. | `session` `no session` |
| [GetLicenseExpirationInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLicenseExpirationInfo/index.md) | Gets the number of days until the server's license and its subscription expire. | `session` `session` `idempotent` |
| [GetLoginSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLoginSettings/index.md) | Gets the anonymous login settings and enabled vertical applications of the vault that serves the given host name, without a session. | `session` `no session` |
| [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. | `session` `session` `idempotent` |
| [GetPublicKeyAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKeyAnonymous/index.md) | Gets the server's RSA public key without a session, for encrypting authentication data before login. | `session` `no session` |
| [GetRPCOverCOMInterface](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetRPCOverCOMInterface/index.md) | Gets RPC over COM interface for accessing M-Files Server. | `session` `no session` |
| [GetVaultConnectionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultConnectionInfo/index.md) | Gets the full connection information of the current vault session, in the form the M-Files COM API uses. | `session` `session` |
| [IsServerRunningInEvaluationMode](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/IsServerRunningInEvaluationMode/index.md) | Tells whether the server runs on an evaluation license, and how many evaluation days are left. | `session` `session` `idempotent` |
| [LoginForAutomaticUpdates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LoginForAutomaticUpdates/index.md) | Logs in for automatic updates. | `session` `no session` |
| [LogInRemote](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/index.md) | Logs in (with authentication) to a remote server. | `session` `no session` |
| [Relogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/Relogin/index.md) | Logs in again by using the current session ID. Used by M-Files' own clients. | `session` `session` |
| [ResolveMaturityOfFeature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ResolveMaturityOfFeature/index.md) | Returns which of the named server feature flags are enabled on this server. | `session` `no session` |
| [SetOpenSessionCheck](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/SetOpenSessionCheck/index.md) | Sets whether administrators are warned about this session when they take the vault offline or do other maintenance. | `session` `session` |
| [VerifyLicenseSubscriptionTime](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/VerifyLicenseSubscriptionTime/index.md) | Fails if the server's license subscription has expired; succeeds otherwise. | `session` `no session` |
---
# IRPCLogin.GetServerCapabilities
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/
Badges: `Vault API / core` `session` `no session` `idempotent`
Gets the features the server supports, without logging in.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetServerCapabilities`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-capabilities`
- **Request:** [`GetServerCapabilitiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md#request)
- **Response:** [`GetServerCapabilitiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session; the result is the same for all callers and can be cached. Check a capability
before using the methods or fields it guards.
These are server-level capabilities. After logging in to a vault, prefer
`session_data.server_vault_capabilities`, which also includes vault-specific capabilities (for
example `facet_search`) as they apply to the user.
## Request: GetServerCapabilitiesRequest
No fields.
## Response: GetServerCapabilitiesResponse
> Nested 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_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Receives the server capabilities. |
| `server_capabilities.vault_login_accounts` | `bool` | Vault supports in-vault login accounts. |
| `server_capabilities.public_link_sharing` | `bool` | Specifies whether sharing public links are allowed. |
| `server_capabilities.latest_version_public_link_sharing` | `bool` | Specifies whether sharing public links for latest versions are allowed. |
| `server_capabilities.facet_search` | `bool` | Specifies whether facet search are allowed. |
| `server_capabilities.property_def_searchability` | `bool` | Specifies whether property definitions can be configured searchable or unsearchable. |
| `server_capabilities.automatic_metadata` | `bool` | Server implements automatic metadata feature and the metadata extraction is enabled on server. |
| `server_capabilities.file_streaming` | `bool` | Specifies whether file streaming is supported. |
| `server_capabilities.search_options2` | `bool` | Server supports search options. |
| `server_capabilities.json_ext_applications` | `bool` | Server supports returning ext. application structs in json format. |
| `server_capabilities.search_referenced_value_list_items` | `bool` | Server supports searching for value list items which are referenced by objects. |
| `server_capabilities.get_text_content_with_options` | `bool` | Server supports calling the new GetTextContentForFile method with options. |
| `server_capabilities.external_repository_object_migration` | `bool` | Server supports external repository object migration. |
| `server_capabilities.client_http_api` | `bool` | Server supports communication with client through HTTP API. |
| `server_capabilities.reverse_grouping_level` | `bool` | Server supports reverse grouping levels. |
| `server_capabilities.replication_configuration_id` | `bool` | Server supports configuration ID in export and import jobs. |
| `server_capabilities.detect_text_language` | `bool` | Server supports detecting the language of plain text. |
| `server_capabilities.async_nacl_change_propagation` | `bool` | Server supports asynchronous NACL change propagation. |
| `server_capabilities.object_data_retrieval_in_chunks` | `bool` | Server supports object data retrieval in chunks. |
| `server_capabilities.async_tasks_retrieval` | `bool` | Server supports retrieving asynchronous tasks. |
| `server_capabilities.find_duplicates` | `bool` | Server supports finding duplicate files. |
| `server_capabilities.favor_full_text_search` | `bool` | Server supports favoring full-text search even if no AnyField conditions exist. |
| `server_capabilities.application_task_queue` | `bool` | Server supports application task queue operations. |
| `server_capabilities.object_permissions_for_client` | `bool` | Server supports ObjectPermissionsForClient. |
| `server_capabilities.undelete_user_account_by_guid` | `bool` | Server supports undeleting a user account by GUID. |
| `server_capabilities.use_user_visible_aclin_searches` | `bool` | Server supports using UserVisibleACL in searches to check users' read access to objects. |
| `server_capabilities.named_value_storage_conflict_detection` | `bool` | Server supports conflict detection when saving named values. |
| `server_capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `server_capabilities.embedded_ui_for_share_point` | `bool` | Server supports embedding vNext UI to the SharePoint. |
| `server_capabilities.embedded_ui_for_salesforce_crm` | `bool` | Server supports embedding vNext UI to the Salesforce. |
| `server_capabilities.async_modify_object_class` | `bool` | Server supports asynchronous object class modification. |
| `server_capabilities.settings_manager` | `bool` | Server supports settings management. |
| `server_capabilities.web_user_interface` | `bool` | Server supports web user interface. |
| `server_capabilities.remove_from_recently_accessed` | `bool` | Server supports removing objects from "Recently Accessed by Me" -view. |
| `server_capabilities.plain_text_password_methods` | `bool` | Server supports plain text password methods. |
| `server_capabilities.ocr_automatic_language_detection` | `bool` | Server supports OCR automatic language detection. |
| `server_capabilities.ground_link` | `bool` | Server supports ground link feature. |
| `server_capabilities.async_aacl_change_propagation` | `bool` | Server supports asynchronous AACL change propagation. |
| `server_capabilities.google_integration_supported` | `bool` | Server supports google g-suite. |
| `server_capabilities.document_compare` | `bool` | Server supports making document comparison requests. |
| `server_capabilities.full_control_vault_user_can_modify_code` | `bool` | Server supports full control vault user can modify code (Cloud Service Fabric Isolated Service). |
| `server_capabilities.broadcast_request_supported` | `bool` | Server supports sending pre-defined broadcast messages through the vault database. |
| `server_capabilities.embedded_ui_for_arc_gis` | `bool` | Server supports embedding vNext UI to the ArcGIS. |
| `server_capabilities.search_in_external_view_folder` | `bool` | Server supports search in external view folder. |
| `server_capabilities.automatic_semantic_alias` | `bool` | Server supports automatic semantic aliases (advanced vault settings). |
| `server_capabilities.automatic_online_transition` | `bool` | Server supports automatic online transition. |
| `server_capabilities.vault_server_attachments` | `bool` | Server supports vault server attachment feature. |
| `server_capabilities.replication_package_list_and_remove` | `bool` | Server supports replication package list and remove feature. |
| `server_capabilities.plugin_replication_allowed_for_vault_admin` | `bool` | Does server support plugin replication for vault admins? |
| `server_capabilities.recurring_notifications` | `bool` | Server supports recurring notifications. |
| `server_capabilities.remove_workflows` | `bool` | Server supports removing workflows as a batch. |
| `server_capabilities.jsoned_workflows_admin` | `bool` | Server supports JSONed workflows admin interface. |
| `server_capabilities.tls_certificates` | `bool` | Server supports configuring TLS certificates. |
| `server_capabilities.attach_vault_options_as_json` | `bool` | Server supports transmitting AttachVaultOptions. |
| `server_capabilities.web_client_sends_telemetry_data` | `bool` | Sending production telemetry data by web clients is enabled. |
| `server_capabilities.ground_link_eot` | `bool` | Server supports ground link EOT feature. |
| `server_capabilities.vault_access_rights64_bits` | `bool` | Server supports 64-bit VAULTACCESS. |
| `server_capabilities.vault_role_manage_private_views` | `bool` | Server supports a vault role for managing private views. |
| `server_capabilities.exclude_vaults_user_cannot_access` | `bool` | Server supports returning only vaults user has access to. |
| `server_capabilities.find_duplicates_of_obj_ver` | `bool` | Server supports finding duplicate of ObjVer. |
| `server_capabilities.add_object_with_files` | `bool` | Server supports adding object with files in single server call. |
| `server_capabilities.folder_uistate_operations_of_view` | `bool` | Server supports accessing and setting Folder UI State of View as structure based data. |
| `server_capabilities.long_smtpnotification_password_supported` | `bool` | Server supports long SMTP notification password. |
| `server_capabilities.can_change_permissions_object_capability` | `bool` | Server reports the "can change permissions" object capability. |
| `server_capabilities.add_new_version_based_on_conflict_object` | `bool` | Server supports adding a new version to the object based on the related deleted conflict object. |
| `server_capabilities.reading_replication_packages_from_new_location_supported` | `bool` | Server can read replication packages whose names end with the full hash. |
| `server_capabilities.writing_replication_packages_to_new_location_supported` | `bool` | Server can write replication packages whose names end with the full hash. |
| `server_capabilities.vault_health_check_supported` | `bool` | Server supports vault health check. |
| `server_capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Server supports that all users can see deleted conflict objects. |
| `server_capabilities.automatic_conflict_resolution` | `bool` | Automatic conflict resolution is enabled in the vault. |
| `server_capabilities.share_private_views` | `bool` | Server supports sharing private views. |
| `server_capabilities.external_mail_source_oauth_proxy_supported` | `bool` | Server supports storing external mail source oauth proxy information. |
| `server_capabilities.async_tasks_range_api` | `bool` | Server supports an API to get a range of asynchronous tasks. |
| `server_capabilities.shared_link_based_wopioperations` | `bool` | Server supports shared link based wopi operations. |
| `server_capabilities.advanced_password_hashes` | `bool` | Server supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `server_capabilities.anonymous_authentication_supported` | `bool` | Server supports anonymous authentication. |
| `server_capabilities.get_default_replication_configuration_supported` | `bool` | Server supports getting default configuration for replication. |
| `server_capabilities.object_version_data_request_with_identity_type_supported` | `bool` | `ObjectVersionDataRequest` supports an identity type. |
| `server_capabilities.rsa_aes_encryption` | `bool` | Encryption with RSA+AES is supported. |
| `server_capabilities.indexer_monitoring_status` | `bool` | Indexer monitoring status is supported. |
| `server_capabilities.green_lights_supported` | `bool` | Green Lights supported. |
| `server_capabilities.allow_code_modification_with_valid_signature_supported` | `bool` | Server supports installation of signed scipts and apps by users. |
| `server_capabilities.mdcc_resolved_on_server` | `bool` | The Metadata Card Configuration is delivered as a pre-resolved from a dedicated virtual NVS namespace. |
| `server_capabilities.new_web_wopico_authoring_supported` | `bool` | WOPI CoAuthoring using New web is supported. |
| `server_capabilities.get_vault_session_info_supported` | `bool` | Server supports returning of vault session info. |
| `server_capabilities.event_log_saved_searches` | `bool` | EvenLog Saved Searches Supported. |
| `server_capabilities.allow_sys_admin_unsigned_code_modification_supported` | `bool` | Sys Admins can install unsigned vault applications and modify unsigned VBScripts even when the signing feature is enabled. |
| `server_capabilities.vault_app_dependencies_supported` | `bool` | If vault app installation can require other vault apps to be installed in the vault. |
| `server_capabilities.dataset_deleted_condition_supported` | `bool` | Server supports deleted/not deleted-condition in an exported dataset definition. |
| `server_capabilities.unified_password_hashes` | `bool` | Server supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `server_capabilities.set_properties_with_missing_required_params_supported` | `bool` | Server supports SetProperties with missing required params. |
| `server_capabilities.index_management_enabled` | `bool` | Index management operations are enabled for the server. |
| `server_capabilities.search_results_sorting` | `bool` | Specifies whether the server supports sorting search results. |
| `server_capabilities.property_action_state_transition_time` | `bool` | Server supports state transition time setting via state property action. |
| `server_capabilities.set_new_web_as_default_client_supported` | `bool` | Server supports set new web as default client. |
| `server_capabilities.ignore_vault_external_data_connection_points` | `bool` | Server supports ignore vault's external data connection points. |
| `server_capabilities.add_user_returns_tasks_before_login` | `bool` | Server supports returning tasks the caller must wait before login to the vault with that user succeeds. |
| `server_capabilities.m_files_link_supported` | `bool` | Server supports the new links and the Link Loading Page. |
| `server_capabilities.can_verify_vault_app_signature` | `bool` | Server supports verification of vault app signatures. |
| `server_capabilities.allow_signed_code_in_import_supported` | `bool` | Server supports allowing signed code importing even if the code import would be otherwise denied for the structure element. |
| `server_capabilities.value_list_item_search_property_conditions` | `bool` | Server supports real property definition based conditions in value list item searches. |
| `server_capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Server supports additive permissions via automatic ACL components. |
| `server_capabilities.set_default_view_from_my_filtered_views_supported` | `bool` | Server supports setting the default view from the user's filtered views. |
| `server_capabilities.set_properties_ex_supported` | `bool` | Server supports the updated SetPropertiesEx call. |
| `server_capabilities.search_results_sorting_by_search_engine` | `bool` | Server supports search results sorting done by search engine. |
| `server_capabilities.async_task_hierarchy_wait_supported` | `bool` | Server supports returning task hierarchy enabling waiting for all tasks matchins search conditions to complete. |
| `server_capabilities.vault_level_optimization_jobs` | `bool` | Server supports vault-level optimization jobs. |
| `server_capabilities.mdcc_conversion_on_server` | `bool` | Server supports converting metadata card configurations between primary and configurator versions. |
| `server_capabilities.template_request_filter_supported` | `bool` | Server supports specifying a filter when requesting templates. |
| `server_capabilities.import_views_with_older_last_modified_supported` | `bool` | Server supports importing views with an older last modified date and time. |
| `server_capabilities.visitor_links_supported` | `bool` | Server supports new interface methods for visitor links. |
| `server_capabilities.notifications_modern_authentication_supported` | `bool` | Server supports modern authentication (OAuth2) to send notifications. |
| `server_capabilities.get_metadata_structure_supported` | `bool` | Server supports providing full metadata structure with one RPC call. |
| `server_capabilities.optimize_vault_job_auto_cancel` | `bool` | Server supports auto-canceling optimize vault jobs. |
| `server_capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Server supports generating authentication configuration for Azure v2.0 endpoint. |
| `server_capabilities.preview_thumbnail_supported` | `bool` | Server supports creating preview thumbnails. |
| `server_capabilities.vault_connection_qrsettings` | `bool` | Server supports vault connection QR settings. |
| `server_capabilities.run_extension_method` | `bool` | Server supports the 'RunExtensionMethod' method. |
| `server_capabilities.structure_item_groups_in_export_supported` | `bool` | Server supports structure item groups in the export job. |
| `server_capabilities.teams_add_on_supported` | `bool` | Server supports teams add-on. |
| `server_capabilities.unified_login_supported` | `bool` | Server support all different types log-in methods through a single method. |
| `server_capabilities.handling_technical_credentials_supported` | `bool` | Server supports handling of login accounts defined as technical credentials. |
| `server_capabilities.jsoned_vault_basic_supported` | `bool` | Server supports JSONed vault basic. |
| `server_capabilities.generate_login_service_auth_conf` | `bool` | Server supports generating authentication configuration for M-Files Login Service. |
| `server_capabilities.new_desktop_supported` | `bool` | Server supports new vNext based Desktop. |
| `server_capabilities.gl_comm_error` | `bool` | Server supports notifying greenlights joining errors and error is on. |
| `server_capabilities.recently_used_values` | `bool` | Server supports storing and returning recently used values for lookup properties in metadata. |
| `server_capabilities.add_object_with_multiple_files` | `bool` | |
| `server_capabilities.new_get_effective_permissions_supported` | `bool` | Server supports new GetEffectivePermissions API. |
| `server_capabilities.sub_folders_in_views` | `bool` | Server supports subfolders in views. |
| `server_capabilities.manual_aad_auth_conf_migration_supported` | `bool` | Server supports manually migrating Azure AD authentication configuration to Login Service. |
| `server_capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Server supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `server_capabilities.entity_version_checking_supported` | `bool` | Server supports entity version numbering to track modification conflicts. |
| `server_capabilities.folder_download_supported` | `bool` | HTTP layer supports downloading folders with download URLs. |
| `server_capabilities.uistate_for_special_folders_supported` | `bool` | Server supports special folder type such as history. |
| `server_capabilities.latest_comment_as_object_data_supported` | `bool` | Server supports getting the latest version comment as part of the object data. |
| `server_capabilities.native_co_authoring_supported` | `bool` | Server supports native co-authoring. |
| `server_capabilities.workflow_state_history` | `bool` | Server supports GetWorkflowStateHistory API. |
| `server_capabilities.block_mfiles_login` | `bool` | Is logging in using M-Files accounts prohibited. |
| `server_capabilities.cloud_management_api_operations` | `bool` | Server supports Cloud Management API Operations. |
| `server_capabilities.reload_application` | `bool` | Server supports 'ReloadApplication' method. |
| `server_capabilities.workflow_descriptions_supported` | `bool` | Workflow, State and State Transition struct with user description fields. |
| `server_capabilities.new_license_api` | `bool` | Server supports new GetLicenseCodeAndSerialNumber API. |
| `server_capabilities.new_wopidiscovery_endpoint_supported` | `bool` | Server supports new WOPI discovery RPC endpoint. |
| `server_capabilities.web_force_session_based_token` | `bool` | M-Files Web Access uses only session-based tokens. |
| `server_capabilities.basic_tier_objects_supported` | `bool` | Vault supports basic-tier objects. |
| `server_capabilities.version_editors_property_supported` | `bool` | Server supports the property with multiple editors for a single object version. |
| `server_capabilities.check_in_external_changes_supported` | `bool` | Server supports the Check in external Changes RPC endpoint. |
| `server_capabilities.sharing_center1_supported` | `bool` | Server supports Sharing center 1 feature. |
| `server_capabilities.get_folder_contents_api_request_response` | `bool` | Server supports GetFolderContents API with request and response structures. |
| `server_capabilities.uixapplication_schema_v6_supported` | `bool` | Server supports UIX Application Schema v6. |
| `server_capabilities.user_and_group_changes` | `bool` | Server supports user and group change versioning and synchronization to Change Hub. |
| `server_capabilities.native_co_authoring_replication_supported` | `bool` | Server supports native co-authoring replication. |
| `server_capabilities.separate_desktop_co_authoring_setting` | `bool` | Server recognizes a vault setting that enables co-authoring for Master Storage separately from Microsoft 365. |
| `server_capabilities.incoming_requests_via_grpc_only` | `bool` | Server uses the gRPC-only routing for incoming requests. |
| `server_capabilities.non_standard_default_for_iis_endpoint` | `bool` | Server uses the non-standard default (7780) for IIS endpoint. |
| `server_capabilities.workspace_personalization_supported` | `bool` | Server supports workspace personalization. |
| `server_capabilities.integration_platform` | `bool` | Server supports Integration Platform. |
| `server_capabilities.check_in_external_changes_returns_visibility` | `bool` | The server supports the post-operation visibility info in CheckInExternalChanges RPC function. |
| `server_capabilities.get_client_settings_for_desktop_supported` | `bool` | Server supports GetClientSettingsByType for M-Files Desktop. |
| `server_capabilities.pdftron_modular_uisupported` | `bool` | Server supports Modular UI PDFTron integration. |
| `server_capabilities.query_search_agent_supported` | `bool` | Server supports QuerySearchAgent RPC endpoint. |
| `server_capabilities.set_tier_supported` | `bool` | Server supports SetTier API and functionality. |
| `server_capabilities.user_group_sync_status_supported` | `bool` | Server supports user group synchronization status. |
| `server_capabilities.downloading_content_from_temp_location_supported` | `bool` | Server supports downloading content from temporary location. |
| `server_capabilities.get_uiversion_info_supported` | `bool` | Server supports GetUIVersionInfo RPC endpoint. |
| `server_capabilities.aino_search_results_summarization_supported` | `bool` | Unused. |
| `server_capabilities.cad_file_preview_supported` | `bool` | Server supports CAD file preview (DWG, DXF, DWT, DGN to PDF conversion). |
| `server_capabilities.declarative_metadata_structure_supported` | `bool` | Collective metadata structure interfaces IRPCDeclarativeMetadataStructureAsProtobuf and IRPCDeclarativeMetadataStructure are available. |
| `server_capabilities.master_storage_malware_detection` | `bool` | Server checks user downloads of Master Storage files against the file's malware verdict, and offers [GetFileMalwareInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileMalwareInfo/index.md) for advisory warnings. |
| `server_capabilities.keep_upload_session_alive_supported` | `bool` | Server supports KeepUploadSessionAlive RPC endpoint. |
| `server_capabilities.purview_labels` | `bool` | Server offers GetSensitivityLabels (IRPCSensitivityLabels), which returns the Microsoft Purview sensitivity labels of files in Master Storage, for advisory label display. |
| `server_capabilities.get_objects_by_external_ids` | `bool` | Server supports looking up objects by their external IDs. |
| `server_capabilities.summarization_agent_supported` | `bool` | Server supports the Aino summarization agent (AI summaries with Q&A). |
| `server_capabilities.dual_preview_supported` | `bool` | Server supports dual preview (SharePoint Embedded preview and PDFTron) for documents in vaults that keep their files in SharePoint Embedded. |
| `server_capabilities.coauthoring_external_idchecked` | `bool` | Server checks the external ID for co-authoring. |
| `server_capabilities.get_index_configurations_for_ixsupported` | `bool` | Server offers GetIndexConfigurationsForIX (IRPCIndexingDataSource2), which returns the vault's search index configuration, without secrets, to a caller who can see all objects. |
| `server_capabilities.draft_object_creation_supported` | `bool` | Server supports creating objects in a draft (pending-upload) state with `AddObjectWithFiles` (`draft`). |
| `server_capabilities.retrieval_of_program_defaults_display_settings_supported` | `bool` | Server supports reading the program default display settings. |
| `server_capabilities.reset_folder_uistate_to_defaults_supported` | `bool` | Server offers ResetFolderUIStateToDefaults (IRPCFolderUISettings), which resets a folder's UI state and returns the resulting state. |
| `server_capabilities.auto_check_in_on_file_close_supported` | `bool` | Server supports automatic check-in when an Office file is closed in Microsoft 365 co-authoring. |
| `server_capabilities.vault_admin_edit_of_replication_job_with_working_directory_supported` | `bool` | Server lets vault administrators modify cloud replication jobs that carry folders, keeping the server-owned working directory and impersonation. |
| `server_capabilities.create_new_object_with_property_metadata_supported` | `bool` | Server supports [CreateNewObjectWithPropertyMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CreateNewObjectWithPropertyMetadata/index.md): a new object and its property value metadata in one call. |
| `server_capabilities.add_object_with_files_with_property_metadata_supported` | `bool` | Server supports [AddObjectWithFilesWithPropertyMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/index.md): a new object with files and its property value metadata in one call. |
| `server_capabilities.direct_file_content_in_add_object_with_files_supported` | `bool` | Server accepts inline file content (`OBJ_FILE_SOURCE_TYPE_FILE_CONTENT`) when creating an object with files. |
| `server_capabilities.set_properties_with_metadata_attributed_to_supported` | `bool` | Server supports [SetPropertiesWithMetadataAttributedTo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/index.md), which records automatic metadata changes as made by a built-in agent user. |
| `server_capabilities.vault_ready_for_m365_storage_permissions_supported` | `bool` | Server offers IsVaultReadyForM365StoragePermissions (IRPCUsersAdmin), which tells whether the vault's users meet the precondition for applying M-Files permissions to Microsoft 365 storage. |
| `server_capabilities.file_upload_stateless_supported` | `bool` | Server supports the `file_ref` uploads of [IRPCFileTransfer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md) and [IRPCFileTransferStreaming](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md). False by default in M-Files Server 26.11, where those methods answer "Not implemented.". |
| `server_capabilities.get_text_content_with_format_supported` | `bool` | Server supports requesting GetTextContentForFile content in a specific FileFormat (plain text or Markdown) and reports the format actually produced. |
| `server_capabilities.persistent_reasoning_metadata_supported` | `bool` | Server supports persisting reasoning metadata. |
| `server_capabilities.agentic_aino_supported` | `bool` | Server supports agentic Aino retrieval. |
| `server_capabilities.folder_tree_creation_supported` | `bool` | Server supports creating a whole traditional folder tree in one request (CreateFolderTree). Not reported for Ground Link proxy vaults. |
| `server_capabilities.get_current_timestamp_for_ixsupported` | `bool` | Server offers GetCurrentTimestampForIX (IRPCIndexingDataSource2), which returns the vault's current indexing position so that a crawl can start from now. |
| `server_capabilities.select_folders_supported` | `bool` | Server supports saving per-user folder selections for view levels (SetFolderSelection) and reporting them. |
---
# IRPCLogin.GetAuthenticationConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/
Badges: `Vault API / core` `session` `no session` `idempotent`
Tells a client, before login, whether to authenticate with an authentication plug-in (single
sign-on) and returns the plug-in's client-side configuration.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetAuthenticationConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-authentication-configuration`
- **Request:** [`GetAuthenticationConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md#request)
- **Response:** [`GetAuthenticationConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. The server looks for a configuration that matches the request; the vault can be
given by `vault_guid` or resolved from `host_name` (the host name the client connects to, as
configured for the vault). A configuration can be limited to one account type (configuration scope
such as `*:WINDOWS:`); it then matches only a request with that `type`. To find the single sign-on
configuration of a vault, set `type` to `ACCOUNT_TYPE_WINDOWS`: users who sign in through an
identity provider have Windows-type login accounts.
- `auth_method` `AUTH_METHOD_PLUGIN`: log in with `AUTH_DATA_TYPE_PLUGIN` using one of
`plugin_infos`. On M-Files Cloud this is the identity provider sign-in.
- `auth_method` `AUTH_METHOD_UNSPECIFIED` with no `plugin_infos`: no plug-in applies; log in with
user name and password or Windows authentication.
`target_plugin_name` must be empty; any other value fails with `E_INVALIDARG`.
## Request: GetAuthenticationConfigurationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `remote_can_be_null` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | Leave unset. Naming a remote server needs a server setting that is off by default. |
| `remote_can_be_null.network_address` | `string` | The network address (name) of the server. |
| `remote_can_be_null.endpoint` | `string` | The endpoint of the server. |
| `remote_can_be_null.protocol_sequence` | `string` | The protocol sequence of the server. |
| `user_name` | `string` | Optional. The user name typed by the user, to find a configuration scoped to it. |
| `domain` | `string` | Optional. The user's domain, to find a configuration scoped to it. |
| `vault_guid` | `string` | Optional. The vault the user is logging in to. When empty or all zeros, the vault is resolved from `host_name`. |
| `host_name` | `string` | Optional. The host name the client uses to reach the server, for example the vault's cloud address. Used to find the vault and host-specific configurations. |
| `type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | The account type to find a configuration for. Leave unset when unknown. Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `target_plugin_name` | `string` | Deprecated. Must be empty; any other value fails with `E_INVALIDARG`. |
| `capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | The client's capabilities, as in `ClientData.capabilities`. |
| `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. |
## Response: GetAuthenticationConfigurationResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `auth_method` | [`AuthMethod`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthMethod/index.md) | `AUTH_METHOD_PLUGIN` when `plugin_infos` contains a usable configuration, `AUTH_METHOD_UNSPECIFIED` otherwise. Values: `AUTH_METHOD_UNSPECIFIED` (0), `AUTH_METHOD_PLUGIN` (3). |
| `plugin_infos[]` | repeated [`PluginInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PluginInfo/index.md) | The matching plug-in configurations. `system_configuration` holds the configuration scope (`Scope`) to send back in `PluginData.configuration_scope`; `plugin_configuration` holds the plug-in's client settings. |
| `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. |
---
# IRPCLogin.LogIn
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/
Badges: `Vault API / core` `session` `no session`
Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is
all zeros.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/LogIn`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/log-in`
- **Request:** [`LogInRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md#request)
- **Response:** [`LogInResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. The session ID comes back in `session_data.session_id` (48 bytes) and goes,
unchanged, into the `mfiles-session-id-bin` header of all later calls.
**User name and password** (`AUTH_DATA_TYPE_CREDENTIALS`) complete in one call. Set
`authentication_data.type` and fill `authentication_data.data.credentials`; the type and the
populated union member must match, an unset type fails with `E_INVALIDARG`. Use this over TLS
only: the password is sent as is.
**Multi-step methods** (Windows authentication, plug-in authentication, the two-leg M-Files
challenge) may need several calls. While the response has no `session_data`, the login is not
done: call `LogIn` again with the next authentication data and the
`authentication_attempt_identifier` from the previous response, placed in the union member's own
`authentication_attempt_identifier` field. The attempt is discarded when it completes or fails.
**Vault GUID.** `login_data.vault_guid` accepts the GUID with or without braces, in any case.
An empty string is not "no vault": it fails with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. Use
`{00000000-0000-0000-0000-000000000000}` for a server-level session. An unknown GUID fails with
`E_MFILES_UNKNOWN_VAULT`; an offline vault with `E_MFILES_VAULT_OFFLINE`.
**Failures.** An unknown user, a wrong password and a login blocked by the server's login attack
protection are all reported as `E_MFILES_AUTHENTICATION_FAILED` (`Authentication failed.`)
without further detail. Do not retry a failed login in a loop. A missing user name fails with
`E_INVALIDARG`.
**Session lifetime.** The session expires when no
[KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) arrives for twice
`session_data.keep_alive_interval_in_seconds`; other calls do not extend it.
`vaults_availability` is filled only for a server-level login on servers that enable it; expect it
to be empty and use [GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md) instead.
## Request: LogInRequest
A structure that specifies the request type for the LogInRequest 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 |
|---|---|---|
| `environment_data` | [`EnvironmentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EnvironmentData/index.md) | Describes the client device. Optional; `client_name` is shown as the session's computer name. |
| `environment_data.client_name` | `string` | A name for the client device, such as its host name. Shown as the session's computer name. Must not start with `@{`. |
| `environment_data.timezone` | [`TimeZoneInformation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TimeZoneInformation/index.md) | The client device's time zone. Leave unset if unknown. |
| `environment_data.timezone.bias_in_minutes` | `int32` | The difference between UTC and local time, in minutes. |
| `environment_data.timezone.standard_name` | `string` | A description for standard time, max length 31. |
| `environment_data.timezone.standard_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from daylight saving time to standard time occurs. |
| `environment_data.timezone.standard_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during standard time. |
| `environment_data.timezone.daylight_name` | `string` | A description for daylight saving time (DST), max length 31. |
| `environment_data.timezone.daylight_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from standard time to daylight saving time occurs. |
| `environment_data.timezone.daylight_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during daylight saving time. |
| `environment_data.host_platform` | `string` | Free-form description of the platform, for example `Windows 11` or `Python 3.13`. |
| `environment_data.device_token` | `string` | A stable, globally unique identifier of the device. Used by M-Files clients that register devices; see [DisconnectDevice](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md). |
| `client_data` | [`ClientData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientData/index.md) | Describes the client software. Set `type` (for example `CLIENT_TYPE_SERVER_API`) and `language`; set `capabilities` only for features your code handles. |
| `client_data.version` | `uint64` | The client's version, packed like `QueryVersionResponse.server_version` (`major << 48 \| minor << 32 \| build << 16 \| patch`). May be 0. If the server administrator has set a minimum client version, older clients are refused with `E_MFILES_INCOMPATIBLE_SERVER_VERSION`. |
| `client_data.capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | Features the client software handles. The server adapts some responses to them, so set only the flags your code implements; leave the rest false. |
| `client_data.capabilities.property_def_searchability` | `bool` | Property definitions can be configured searchable or unsearchable. |
| `client_data.capabilities.unmanaged_objects` | `bool` | Client understands unmanaged objects. |
| `client_data.capabilities.extension_authentication_data_push` | `bool` | Client supports data push for extension authentications. |
| `client_data.capabilities.custom_api_data_push` | `bool` | Client supports server data push for M-Files API & custom implementations. |
| `client_data.capabilities.unknown_file_size` | `bool` | Client can handle unknown or estimated file size. |
| `client_data.capabilities.typed_metadata_suggestions` | `bool` | Client can handle metadata suggestions to all M-Files types. |
| `client_data.capabilities.long_authentication_attempt_identifier` | `bool` | The client handles the long (32-byte) authentication attempt identifier in `AuthenticationAttemptIdentifier.data`. |
| `client_data.capabilities.reverse_grouping_level` | `bool` | Client supports reverse grouping levels. |
| `client_data.capabilities.object_permissions_for_client` | `bool` | Client supports ObjectPermissionsForClient. |
| `client_data.capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `client_data.capabilities.smart_search` | `bool` | Client supports Smart Search engine type. |
| `client_data.capabilities.recurring_notifications` | `bool` | Client supports recurring notifications. |
| `client_data.capabilities.smart_search_facets` | `bool` | Client supports smart search facets. |
| `client_data.capabilities.vault_role_manage_private_views` | `bool` | Client supports a vault role for managing private views. |
| `client_data.capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Client supports that all users can see deleted conflict objects. |
| `client_data.capabilities.advanced_password_hashes` | `bool` | Client supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `client_data.capabilities.anonymous_authentication` | `bool` | Client supports anonymous authentication. |
| `client_data.capabilities.dataset_deleted_condition` | `bool` | Client supports deleted/not deleted-condition in a dataset definition. |
| `client_data.capabilities.unified_password_hashes` | `bool` | Client supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `client_data.capabilities.duplicates_view` | `bool` | Client supports the duplicates view. |
| `client_data.capabilities.property_action_state_transition_time` | `bool` | Client supports state transition time setting via state property action. |
| `client_data.capabilities.at_mentions` | `bool` | Client supports the @mentions in comment texts. |
| `client_data.capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Client supports additive permissions via automatic ACL components. |
| `client_data.capabilities.vault_level_optimization_jobs` | `bool` | Client supports vault-level optimization jobs. |
| `client_data.capabilities.visitor_links_supported` | `bool` | Client supports new interface methods for visitor links. |
| `client_data.capabilities.object_type_filter_multi_select_views` | `bool` | Client supports multiple object types as a filter for views and advanced searches. |
| `client_data.capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Client supports generating authentication configuration for Azure v2.0 endpoint. |
| `client_data.capabilities.structure_item_groups_in_export` | `bool` | Client supports structure item groups in the export job. |
| `client_data.capabilities.aino_search` | `bool` | Client supports Aino Search engine type. |
| `client_data.capabilities.conversation_history` | `bool` | Client supports conversation history. |
| `client_data.capabilities.generate_login_service_auth_conf` | `bool` | Client supports generating authentication configuration for M-Files Login Service. |
| `client_data.capabilities.sub_folders_in_views` | `bool` | Client supports subfolders in views. |
| `client_data.capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Client supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `client_data.capabilities.entity_version_checking_supported` | `bool` | Client supports entity version numbering to track modification conflicts. |
| `client_data.capabilities.workflow_descriptions_supported` | `bool` | Client supports workflow descriptions. |
| `client_data.capabilities.property_value_metadata_supported` | `bool` | Client supports setting and retrieving property value metadata. |
| `client_data.capabilities.object_type_grouping_for_relationships` | `bool` | Client supports object type based grouping for relationships. |
| `client_data.capabilities.draft_objects` | `bool` | Client supports draft objects in discovery results. |
| `client_data.language` | `string` | The client's language, for example `en`. For [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md), empty means the language of the existing session. |
| `client_data.type` | [`ClientType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ClientType/index.md) | The kind of client. Applications use `CLIENT_TYPE_SERVER_API`. |
| `client_data.type_specifier` | `string` | Optional free-form name of the client application. |
| `login_data` | [`LoginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LoginData/index.md) | The target vault and session options. `vault_guid` is required; see Remarks. |
| `login_data.server_hostname` | `string` | The host name the client used to reach the server. Optional for user name and password logins. Anonymous logins, and server-level logins on servers with vault login accounts, use it to find the vault configured for that host name. |
| `login_data.vault_guid` | `string` | The vault to log in to, as a GUID string with or without braces, in any case. Use `{00000000-0000-0000-0000-000000000000}` for a server-level session; an empty string is rejected with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. |
| `login_data.is_administrative` | `bool` | True for administrative tools that manage the vault rather than work with documents, as M-Files Admin does. Applications leave it false. |
| `login_data.client_session_timeout_in_seconds` | `uint32` | Optional. Requests a longer idle timeout for a vault session. Honored only when it is at least the server's session timeout and at most 7 days (or the server timeout if that is longer); otherwise, and for server-level sessions, the server timeout applies. The effective value shows as `SessionData.keep_alive_interval_in_seconds`, which is half of it. |
| `authentication_data` | [`AuthDataClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClient/index.md) | How the caller proves its identity: `type` plus the matching member of `data`. |
| `authentication_data.type` | [`AuthDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthDataType/index.md) | The authentication method. Must match the member set in `data`; unset fails with `E_INVALIDARG`. For user name and password use `AUTH_DATA_TYPE_CREDENTIALS`. Values: `AUTH_DATA_TYPE_UNDEFINED` (0), `AUTH_DATA_TYPE_MFILES_LEG1` (1), `AUTH_DATA_TYPE_MFILES_LEG2` (2), `AUTH_DATA_TYPE_WINDOWS` (3), `AUTH_DATA_TYPE_PLUGIN` (4), `AUTH_DATA_TYPE_CREDENTIALS` (5), `AUTH_DATA_TYPE_ANONYMOUS` (6). |
| `authentication_data.data` | [`AuthDataClientUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md) | The method's data. Set exactly the member that `type` names. |
| `authentication_data.data.mfiles_leg1` | [`AuthDataClientUnion.MFilesLeg1Data`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-MFilesLeg1Data) (oneof data) | First call of the two-step M-Files challenge login (`AUTH_DATA_TYPE_MFILES_LEG1`). |
| `authentication_data.data.mfiles_leg2` | [`AuthDataClientUnion.MFilesLeg2Data`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-MFilesLeg2Data) (oneof data) | Second call of the two-step M-Files challenge login (`AUTH_DATA_TYPE_MFILES_LEG2`). |
| `authentication_data.data.windows` | [`AuthDataClientUnion.WindowsData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-WindowsData) (oneof data) | Windows authentication tokens (`AUTH_DATA_TYPE_WINDOWS`), possibly over several calls. |
| `authentication_data.data.plugin` | [`AuthDataClientUnion.PluginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-PluginData) (oneof data) | Authentication through a plug-in such as single sign-on (`AUTH_DATA_TYPE_PLUGIN`). |
| `authentication_data.data.credentials` | [`Credentials`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Credentials/index.md) (oneof data) | User name and password (`AUTH_DATA_TYPE_CREDENTIALS`). Completes in one call. |
| `authentication_data.data.anonymous` | [`AuthDataClientUnion.AnonymousData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-AnonymousData) (oneof data) | Anonymous login (`AUTH_DATA_TYPE_ANONYMOUS`), when the vault allows it. Has no data. |
| `authentication_data.certificate_proof` | `string` | Leave empty. Used only when the server requires client certificates. |
| `authentication_data.is_certificate_validated` | `bool` | Leave false. Set only by M-Files proxies that validate client certificates themselves. |
## Response: LogInResponse
A structure that specifies the response type for the LogIn method.
> Nested message fields are expanded to depth 2 only, to keep the page small (the full expansion has more rows); follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `authentication_data` | [`AuthDataServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataServer/index.md) | The server's half of the authentication exchange. For multi-step methods it carries the next challenge, whether the login is done, and the attempt identifier to send back. For `AUTH_DATA_TYPE_CREDENTIALS` there is nothing to act on. |
| `authentication_data.type` | [`AuthDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthDataType/index.md) | The authentication method, as in the request. Values: `AUTH_DATA_TYPE_UNDEFINED` (0), `AUTH_DATA_TYPE_MFILES_LEG1` (1), `AUTH_DATA_TYPE_MFILES_LEG2` (2), `AUTH_DATA_TYPE_WINDOWS` (3), `AUTH_DATA_TYPE_PLUGIN` (4), `AUTH_DATA_TYPE_CREDENTIALS` (5), `AUTH_DATA_TYPE_ANONYMOUS` (6). |
| `authentication_data.data` | [`AuthDataServerUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataServerUnion/index.md) | Method-specific reply: a challenge, a token to pass on, or nothing. |
| `authentication_data.authentication_attempt_identifier` | [`AuthenticationAttemptIdentifier`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthenticationAttemptIdentifier/index.md) | Identifies this login attempt. In multi-step methods, send it back in the next call, in the `authentication_attempt_identifier` field of the request's union member. Ignore it for `AUTH_DATA_TYPE_CREDENTIALS`. |
| `session_data` | [`SessionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionData/index.md) | The new session, set when the login is complete and unset while a multi-step login is still in progress. |
| `session_data.session_id` | `bytes` | The session ID (48 bytes). Send it unchanged in the `mfiles-session-id-bin` metadata header of every call that needs a session. |
| `session_data.account_name` | `string` | The login account name, with the case stored on the server. |
| `session_data.access_rights` | [`SessionAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionAccess/index.md) | What the session may do on server level and in the vault, regardless of object permissions. |
| `session_data.server_vault_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Capabilities of the server and, for vault sessions, the vault, as they apply to this user. More precise than [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md). |
| `session_data.locale` | `uint32` | The Windows locale ID used for sorting, for example 1033. |
| `session_data.keep_alive_interval_in_seconds` | `uint32` | Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) at least this often. It is half of the session's idle timeout. |
| `session_data.use_strict_set_equality_comparison` | `bool` | If false, not equal type comparisons are performed in pre-MF11 style in which it is enough that at least one of the left-side values does not match any of the right-side values in order to treat the left and right values unequal. If true, none of the left-side values can match any of the right-side values in order to treat the left and right values unequal i.e. pure set-based exclusion. Prefer using the new comparison style. The old behavior is provided for compatibility reasons. |
| `session_data.product_mode` | [`ProductMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ProductMode/index.md) | The edition of the server license. Values: `PRODUCT_MODE_FULL` (0), `PRODUCT_MODE_EXPRESS` (1), `PRODUCT_MODE_BUSINESS` (2). |
| `session_data.vault_data` | [`VaultData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultData/index.md) | The user's identity in the vault. Unset for a server-level session. |
| `session_data.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Whether the login account is an M-Files or a Windows account. Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `session_data.server_data` | [`ServerData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerData/index.md) | The server's license serial number and deployment type. |
| `session_data.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license the session uses. 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). |
| `session_data.keep_upload_session_alive_interval_in_seconds` | `uint32` | Keep a file upload session alive at least this often (half of the upload session timeout). |
| `vaults_availability` | [`VaultsAvailabilityOnServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultsAvailabilityOnServer/index.md) | Online and offline vaults the user can see, only for a server-level login and only on servers that enable this; otherwise empty. |
| `vaults_availability.vaults_online[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Vaults that are online and visible to the user. |
| `vaults_availability.vaults_offline[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Vaults that are offline (for example under maintenance) and visible to the user. |
| `vaults_availability.ground_link_proxies_online[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Online Ground Link proxy vaults. |
| `vaults_availability.ground_link_proxies_offline[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Offline Ground Link proxy vaults. |
## Related methods
- [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md): Tells the server that the session is still in use, so that it does not expire.
- [IRPCVaults.GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md): Lists the vaults on the server that the session's user can see.
- [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md): Opens a new session to a vault (or the server) for the user of an existing session, without authenticating again.
- [LogInRemote](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/index.md): Logs in (with authentication) to a remote server.
---
# IRPCLogin.LogInWithSession
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/
Badges: `Vault API / core` `session` `session`
Opens a new session to a vault (or the server) for the user of an existing session, without
authenticating again.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/LogInWithSession`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/log-in-with-session`
- **Request:** [`LogInWithSessionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md#request)
- **Response:** [`LogInWithSessionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Send the existing session in `mfiles-session-id-bin`; it can be a server-level or a vault session.
The response carries a new session with its own session ID; the original session stays valid and
must be logged out separately.
The typical use is: `LogIn` once at server level, list vaults with
[GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md), then open one session per vault with this method.
The user must have access to the target vault. If `client_data.language` is empty the language of
the existing session is used. `login_data.vault_guid` follows the rules of
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): the all-zero GUID opens a server-level session.
An offline vault is refused with `E_MFILES_VAULT_OFFLINE`, except for an administrative login that
the server allows during maintenance.
## Request: LogInWithSessionRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `client_data` | [`ClientData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientData/index.md) | Describes the client software, as in `LogIn`. |
| `client_data.version` | `uint64` | The client's version, packed like `QueryVersionResponse.server_version` (`major << 48 \| minor << 32 \| build << 16 \| patch`). May be 0. If the server administrator has set a minimum client version, older clients are refused with `E_MFILES_INCOMPATIBLE_SERVER_VERSION`. |
| `client_data.capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | Features the client software handles. The server adapts some responses to them, so set only the flags your code implements; leave the rest false. |
| `client_data.capabilities.property_def_searchability` | `bool` | Property definitions can be configured searchable or unsearchable. |
| `client_data.capabilities.unmanaged_objects` | `bool` | Client understands unmanaged objects. |
| `client_data.capabilities.extension_authentication_data_push` | `bool` | Client supports data push for extension authentications. |
| `client_data.capabilities.custom_api_data_push` | `bool` | Client supports server data push for M-Files API & custom implementations. |
| `client_data.capabilities.unknown_file_size` | `bool` | Client can handle unknown or estimated file size. |
| `client_data.capabilities.typed_metadata_suggestions` | `bool` | Client can handle metadata suggestions to all M-Files types. |
| `client_data.capabilities.long_authentication_attempt_identifier` | `bool` | The client handles the long (32-byte) authentication attempt identifier in `AuthenticationAttemptIdentifier.data`. |
| `client_data.capabilities.reverse_grouping_level` | `bool` | Client supports reverse grouping levels. |
| `client_data.capabilities.object_permissions_for_client` | `bool` | Client supports ObjectPermissionsForClient. |
| `client_data.capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `client_data.capabilities.smart_search` | `bool` | Client supports Smart Search engine type. |
| `client_data.capabilities.recurring_notifications` | `bool` | Client supports recurring notifications. |
| `client_data.capabilities.smart_search_facets` | `bool` | Client supports smart search facets. |
| `client_data.capabilities.vault_role_manage_private_views` | `bool` | Client supports a vault role for managing private views. |
| `client_data.capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Client supports that all users can see deleted conflict objects. |
| `client_data.capabilities.advanced_password_hashes` | `bool` | Client supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `client_data.capabilities.anonymous_authentication` | `bool` | Client supports anonymous authentication. |
| `client_data.capabilities.dataset_deleted_condition` | `bool` | Client supports deleted/not deleted-condition in a dataset definition. |
| `client_data.capabilities.unified_password_hashes` | `bool` | Client supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `client_data.capabilities.duplicates_view` | `bool` | Client supports the duplicates view. |
| `client_data.capabilities.property_action_state_transition_time` | `bool` | Client supports state transition time setting via state property action. |
| `client_data.capabilities.at_mentions` | `bool` | Client supports the @mentions in comment texts. |
| `client_data.capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Client supports additive permissions via automatic ACL components. |
| `client_data.capabilities.vault_level_optimization_jobs` | `bool` | Client supports vault-level optimization jobs. |
| `client_data.capabilities.visitor_links_supported` | `bool` | Client supports new interface methods for visitor links. |
| `client_data.capabilities.object_type_filter_multi_select_views` | `bool` | Client supports multiple object types as a filter for views and advanced searches. |
| `client_data.capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Client supports generating authentication configuration for Azure v2.0 endpoint. |
| `client_data.capabilities.structure_item_groups_in_export` | `bool` | Client supports structure item groups in the export job. |
| `client_data.capabilities.aino_search` | `bool` | Client supports Aino Search engine type. |
| `client_data.capabilities.conversation_history` | `bool` | Client supports conversation history. |
| `client_data.capabilities.generate_login_service_auth_conf` | `bool` | Client supports generating authentication configuration for M-Files Login Service. |
| `client_data.capabilities.sub_folders_in_views` | `bool` | Client supports subfolders in views. |
| `client_data.capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Client supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `client_data.capabilities.entity_version_checking_supported` | `bool` | Client supports entity version numbering to track modification conflicts. |
| `client_data.capabilities.workflow_descriptions_supported` | `bool` | Client supports workflow descriptions. |
| `client_data.capabilities.property_value_metadata_supported` | `bool` | Client supports setting and retrieving property value metadata. |
| `client_data.capabilities.object_type_grouping_for_relationships` | `bool` | Client supports object type based grouping for relationships. |
| `client_data.capabilities.draft_objects` | `bool` | Client supports draft objects in discovery results. |
| `client_data.language` | `string` | The client's language, for example `en`. For [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md), empty means the language of the existing session. |
| `client_data.type` | [`ClientType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ClientType/index.md) | The kind of client. Applications use `CLIENT_TYPE_SERVER_API`. |
| `client_data.type_specifier` | `string` | Optional free-form name of the client application. |
| `login_data` | [`LoginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LoginData/index.md) | The target vault (`vault_guid`) and session options. |
| `login_data.server_hostname` | `string` | The host name the client used to reach the server. Optional for user name and password logins. Anonymous logins, and server-level logins on servers with vault login accounts, use it to find the vault configured for that host name. |
| `login_data.vault_guid` | `string` | The vault to log in to, as a GUID string with or without braces, in any case. Use `{00000000-0000-0000-0000-000000000000}` for a server-level session; an empty string is rejected with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. |
| `login_data.is_administrative` | `bool` | True for administrative tools that manage the vault rather than work with documents, as M-Files Admin does. Applications leave it false. |
| `login_data.client_session_timeout_in_seconds` | `uint32` | Optional. Requests a longer idle timeout for a vault session. Honored only when it is at least the server's session timeout and at most 7 days (or the server timeout if that is longer); otherwise, and for server-level sessions, the server timeout applies. The effective value shows as `SessionData.keep_alive_interval_in_seconds`, which is half of it. |
## Response: LogInWithSessionResponse
> Nested message fields are expanded to depth 2 only, to keep the page small (the full expansion has more rows); follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `session_data` | [`SessionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionData/index.md) | The new session. Use its `session_id` for calls to the target vault. |
| `session_data.session_id` | `bytes` | The session ID (48 bytes). Send it unchanged in the `mfiles-session-id-bin` metadata header of every call that needs a session. |
| `session_data.account_name` | `string` | The login account name, with the case stored on the server. |
| `session_data.access_rights` | [`SessionAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionAccess/index.md) | What the session may do on server level and in the vault, regardless of object permissions. |
| `session_data.server_vault_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Capabilities of the server and, for vault sessions, the vault, as they apply to this user. More precise than [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md). |
| `session_data.locale` | `uint32` | The Windows locale ID used for sorting, for example 1033. |
| `session_data.keep_alive_interval_in_seconds` | `uint32` | Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) at least this often. It is half of the session's idle timeout. |
| `session_data.use_strict_set_equality_comparison` | `bool` | If false, not equal type comparisons are performed in pre-MF11 style in which it is enough that at least one of the left-side values does not match any of the right-side values in order to treat the left and right values unequal. If true, none of the left-side values can match any of the right-side values in order to treat the left and right values unequal i.e. pure set-based exclusion. Prefer using the new comparison style. The old behavior is provided for compatibility reasons. |
| `session_data.product_mode` | [`ProductMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ProductMode/index.md) | The edition of the server license. Values: `PRODUCT_MODE_FULL` (0), `PRODUCT_MODE_EXPRESS` (1), `PRODUCT_MODE_BUSINESS` (2). |
| `session_data.vault_data` | [`VaultData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultData/index.md) | The user's identity in the vault. Unset for a server-level session. |
| `session_data.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Whether the login account is an M-Files or a Windows account. Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `session_data.server_data` | [`ServerData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerData/index.md) | The server's license serial number and deployment type. |
| `session_data.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license the session uses. 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). |
| `session_data.keep_upload_session_alive_interval_in_seconds` | `uint32` | Keep a file upload session alive at least this often (half of the upload session timeout). |
## Related methods
- [IRPCVaults.GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md): Lists the vaults on the server that the session's user can see.
- [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
---
# IRPCLogin.KeepAlive
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/
Badges: `Vault API / core` `session` `session` `idempotent`
Tells the server that the session is still in use, so that it does not expire.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/KeepAlive`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/keep-alive`
- **Request:** [`KeepAliveRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md#request)
- **Response:** [`KeepAliveResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Call it at least every `session_data.keep_alive_interval_in_seconds` seconds (half the server's
session timeout; 450 seconds with the default 15-minute timeout). Only this call resets the idle
timer; other calls do not. When the timeout elapses, the session expires.
`KeepAlive` fails with `UNAUTHENTICATED` when the session has expired or was logged out. Then log
in again with [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md).
## Request: KeepAliveRequest
No fields.
## Response: KeepAliveResponse
No fields.
## Related methods
- [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
---
# IRPCLogin.LogOut
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/
Badges: `Vault API / core` `session` `session`
Ends the session and releases its license.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/LogOut`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/log-out`
- **Request:** [`LogOutRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/index.md#request)
- **Response:** [`LogOutResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogOut/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Send the session to end in `mfiles-session-id-bin`. After this, the session ID is rejected with
`UNAUTHENTICATED`.
The vault's "before logout" event handlers may fail without stopping the logout. Sessions that
vault applications receive from the server cannot be logged out (`E_MFILES_ACCESS_DENIED`).
## Request: LogOutRequest
No fields.
## Response: LogOutResponse
No fields.
---
# IRPCLogin.GetVaultSessionInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/
Badges: `Vault API / core` `session` `session` `returns metadata structure version`
Gets basic information about the current vault session: server version and ID, vault GUID and
name, and the state of the server push channel.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetVaultSessionInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-session-info`
- **Request:** [`GetVaultSessionInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/index.md#request)
- **Response:** [`GetVaultSessionInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **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)
## Remarks
Requires a vault session; a server-level session fails with `E_MFILES_LOGIN_REQUIRED`. A cheap
way to check that a session is still valid. The response also carries the vault's metadata
version in the `mfiles-metadata-version-bin` trailer.
For the user's identity, groups and access rights, use the `session_data` returned at login.
## Request: GetVaultSessionInfoRequest
No fields.
## Response: GetVaultSessionInfoResponse
> Nested 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_session_info` | [`VaultSessionInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultSessionInfo/index.md) | The vault session information of the user's session. |
| `vault_session_info.session_id` | `bytes` | The session's ID, the same bytes as in `mfiles-session-id-bin`. |
| `vault_session_info.server_version` | `string` | The server version as text, for example `26.11.16645.0`. |
| `vault_session_info.server_id` | `string` | The GUID of the server. |
| `vault_session_info.vault_guid` | `string` | The GUID of the vault. |
| `vault_session_info.vault_display_name` | `string` | The name of the vault for display purposes. |
| `vault_session_info.attachment_guid` | `string` | The vault's current attachment GUID, as `VaultData.vault_attachment`. |
| `vault_session_info.server_data_push_status` | [`ServerDataPushStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerDataPushStatus/index.md) | Whether the session has an open server push channel. Values: `SERVER_DATA_PUSH_STATUS_UNINITIALIZED` (0), `SERVER_DATA_PUSH_STATUS_REGISTERED` (1), `SERVER_DATA_PUSH_STATUS_NOT_REGISTERED` (2), `SERVER_DATA_PUSH_STATUS_INVALID` (3). |
---
# IRPCLogin.ChangePassword
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ChangePassword/
Badges: `Vault API / core` `session` `session`
Changes the M-Files password of the logged-in account.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/ChangePassword`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-password`
- **Request:** [`ChangePasswordRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ChangePassword/index.md#request)
- **Response:** [`ChangePasswordResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ChangePassword/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Failed attempts count towards the server's login attack protection, like failed logins.
Always set `password_format` to `PASSWORD_FORMAT_SEE_OTHER_PARAMS` and `passwords_unhashed` to
true: the proto3 default of `password_format` selects a deprecated format.
After the change the server logs the account out of all vaults on the server, so expect to log in
again with the new password.
## Request: ChangePasswordRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `old_password` | `string` | The current password, in the form `password_format`, `password_encryption` and `passwords_unhashed` describe. |
| `new_password` | `string` | The new password, in the same form as `old_password`. |
| `password_format` | [`PasswordFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordFormat/index.md) | Set to `PASSWORD_FORMAT_SEE_OTHER_PARAMS`. The other values are deprecated and override `password_encryption`, `passwords_unhashed` and `password_hash_algorithm_desired`. 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) | How the passwords are encrypted in transit. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `passwords_unhashed` | `bool` | Set to true and send the passwords as entered. Pre-hashed passwords are accepted only with MD5. |
| `password_hash_algorithm_desired` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | The algorithm the server uses to store the new password. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
## Response: ChangePasswordResponse
No fields.
---
# IRPCLogin.CreateUserSession
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/CreateUserSession/
Badges: `Vault API / core` `session` `session` `idempotent`
Opens a session that acts as another user of the vault.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/CreateUserSession`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-user-session`
- **Request:** [`CreateUserSessionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/CreateUserSession/index.md#request)
- **Response:** [`CreateUserSessionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/CreateUserSession/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files server-side components; applications rarely need it. Allowed only for a vault
session of a local Windows administrator logged in on the server computer; all other sessions
get `E_MFILES_ACCESS_DENIED`, including vault administrators. The new session uses a read-only
license.
## Request: CreateUserSessionRequest
> Nested 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_id` | `int32` | The ID of the user account (in the session's vault) to act as. |
## Response: CreateUserSessionResponse
> Nested 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_info` | [`SessionInfoServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionInfoServer/index.md) | The new session. Send its `session_id` in `mfiles-session-id-bin`. |
| `session_info.session_id` | `bytes` | Session ID when the login process has been completed successfully. |
| `session_info.keep_alive_interval_in_seconds` | `uint32` | The number of seconds that can pass between KeepAlive calls before MFServer closes the session. |
| `session_info.user_id` | `int32` | The M-Files Account ID of the logged-in user. |
| `session_info.account_name` | `string` | The M-Files Account name of the logged-in user. |
| `session_info.session_access_rights` | [`SessionAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionAccess/index.md) | The access rights of this session. |
| `session_info.session_access_rights.server_access` | [`ServerAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md) | The session's server-level access rights. |
| `session_info.session_access_rights.vault_access` | [`VaultAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md) | The session's vault-level access rights. |
| `session_info.session_access_rights.object_access` | [`ObjectAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectAccess/index.md) | The session's object-level access rights regardless of object ACLs. |
| `session_info.session_access_rights.object_type_access` | [`ObjectTypeAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeAccess/index.md) | The session's object type-level access rights regardless of object type ACLs. |
| `session_info.session_access_rights.property_def_access` | [`PropertyDefAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAccess/index.md) | The session's property definition-level access rights regardless of property definition ACLs. |
| `session_info.substitute_users[]` | repeated [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The user ID of this session's account, as well as the users for which the user is a substitute. The first ID in the vector is the user ID. Others are the IDs of the users for which the user is a substitute. |
| `session_info.substitute_users[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `session_info.substitute_users[].id` | `int32` | User or user group. |
| `session_info.user_and_group_memberships[]` | repeated [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The user ID of this session's account, as well as the groups to which the user belongs either directly or indirectly. The first ID in the vector is the user ID. Others are group IDs. |
| `session_info.user_and_group_memberships[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `session_info.user_and_group_memberships[].id` | `int32` | User or user group. |
| `session_info.is_internal_user` | `bool` | Is the user an internal user? |
| `session_info.use_strict_set_equality_comparison` | `bool` | If false, not equal type comparisons are performed in pre-MF11 style in which it is enough that at least one of the left-side values does not match any of the right-side values in order to treat the left and right values unequal. If true, none of the left-side values can match any of the right-side values in order to treat the left and right values unequal i.e. pure set-based exclusion. Prefer using the new comparison style. The old behavior is provided for compatibility reasons. |
| `session_info.product_mode` | [`ProductMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ProductMode/index.md) | Product mode. Values: `PRODUCT_MODE_FULL` (0), `PRODUCT_MODE_EXPRESS` (1), `PRODUCT_MODE_BUSINESS` (2). |
| `session_info.language` | [`Language`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) | The user's language in the vault. The code and the name may be empty. |
| `session_info.language.id` | `int32` | Language ID. |
| `session_info.language.name` | `string` | The name of the language. |
| `session_info.language.language_code` | `string` | Language indentifier, e.g. the ISO 639-1 or ISO 639-2 language code such as "en" or "eng". |
| `session_info.timezone` | `bytes` | The serialized time zone information (TIME_ZONE_INFORMATION) of this session. |
| `session_info.client_culture` | `string` | The client software culture for this session. |
| `session_info.acl_mode` | [`ACLMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ACLMode/index.md) | The ACL mode of the vault. Ignore it for a session that is not a vault session. Values: `ACLMODE_SIMPLE` (0), `ACLMODE_COMPONENT_BASED` (1). |
| `session_info.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license type of the logged-in user. 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). |
| `session_info.keep_upload_session_alive_interval_in_seconds` | `uint32` | Keep a file upload session alive at least this often. |
---
# IRPCLogin.DisconnectDevice
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/
Badges: `Vault API / core` `session` `session`
Removes a device registration (device token) of the logged-in user in the session's vault.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/DisconnectDevice`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/disconnect-device`
- **Request:** [`DisconnectDeviceRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md#request)
- **Response:** [`DisconnectDeviceResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients that register a device token through `EnvironmentData.device_token` at
login; applications rarely need it. Requires a vault session.
## Request: DisconnectDeviceRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `device_token` | `string` | The device token of the device to be disconnected from the server. |
## Response: DisconnectDeviceResponse
No fields.
---
# IRPCLogin.GetAuthenticationPlugins
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationPlugins/
Badges: `Vault API / core` `session` `no session`
Lists the authentication plug-ins installed on the server, without their configurations.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetAuthenticationPlugins`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-authentication-plugins`
- **Request:** [`GetAuthenticationPluginsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationPlugins/index.md#request)
- **Response:** [`GetAuthenticationPluginsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationPlugins/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. `is_default` is always false and no configurations are returned; use
[GetAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md) to get
the configuration a login needs. Leave `remote_can_be_null` unset.
## Request: GetAuthenticationPluginsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `remote_can_be_null` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | If set, specifies the address of the remote server. |
| `remote_can_be_null.network_address` | `string` | The network address (name) of the server. |
| `remote_can_be_null.endpoint` | `string` | The endpoint of the server. |
| `remote_can_be_null.protocol_sequence` | `string` | The protocol sequence of the server. |
| `vault_guid` | `string` | If not empty, specifies the GUID of the target vault. |
| `scope_independent_only` | `bool` | If true, only scope-independent plugins are returned. |
## Response: GetAuthenticationPluginsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `plugins[]` | repeated [`PluginInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PluginInfo/index.md) | Receives the plugin information. |
| `plugins[].is_default` | `bool` | True if this is the default configuration. |
| `plugins[].is_scope_independent` | `bool` | True if the plug-in can be used without a configuration scope. |
| `plugins[].name` | `string` | The configuration's name. Send it as `PluginData.plugin_name`. |
| `plugins[].assembly_name` | `string` | The plug-in's implementation, for example `MFiles.AuthenticationProviders.OAuth`. |
| `plugins[].bridge_class_name` | `string` | Internal to the server. |
| `plugins[].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`. |
| `plugins[].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. |
| `plugins[].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`. |
| `plugins[].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. |
## Related methods
- [GetAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetAuthenticationConfiguration/index.md): Tells a client, before login, whether to authenticate with an authentication plug-in (single sign-on) and returns the plug-in's client-side configuration.
---
# IRPCLogin.GetClientSettingsByType
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetClientSettingsByType/
Badges: `Vault API / core` `session` `no session`
Gets client settings (theme, timeouts, banners, web security settings) for an M-Files web,
desktop or Outlook client.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetClientSettingsByType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-client-settings-by-type`
- **Request:** [`GetClientSettingsByTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetClientSettingsByType/index.md#request)
- **Response:** [`GetClientSettingsByTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetClientSettingsByType/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files' own web and desktop clients; applications rarely need it. Only vNext, web and
Outlook client types are supported; other types, including `CLIENT_TYPE_SERVER_API`, fail with
`E_NOTIMPL`.
## Request: GetClientSettingsByTypeRequest
Struct for Client settings request data.
> Nested 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 GUID of the vault whose client settings to get. |
| `host_name` | `string` | The host name of the client computer. |
| `client_type` | [`ClientType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ClientType/index.md) | Specifies the type of client( Desktop, Web, etc). |
| `client_setting_flag` | [`CLIENTSETTINGFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CLIENTSETTINGFLAGS/index.md) | Flags that control this operation. |
| `client_setting_flag.all` | `bool` | Specifies all flags set; Including any future flags. |
| `client_setting_flag.theme` | `bool` | Theme flag |
| `client_setting_flag.session_timeout` | `bool` | Client session timeout. |
| `client_setting_flag.default_web_client` | `bool` | Default Web Client. |
| `client_setting_flag.add_in_settings` | `bool` | Addin Settings. |
| `client_setting_flag.default_web_client_iis` | `bool` | Default Web Client for IIS. |
| `client_setting_flag.web_access_cors` | `bool` | CORS settings of Classic web access. |
| `client_setting_flag.migrate_classic_web_url` | `bool` | Redirect classic web urls. |
| `client_setting_flag.migrate_web_link_to_online_web` | `bool` | Migrate web links to online web app (Account layer). |
| `client_setting_flag.custom_banner` | `bool` | Custom banner flag |
| `client_setting_flag.idle_session_timeout` | `bool` | Idle session timeout. |
## Response: GetClientSettingsByTypeResponse
Struct for Client settings information.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `theme_configuration` | [`ThemeConfiguration`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ThemeConfiguration/index.md) | The vault's UI theme (colors and logos) for the client. |
| `theme_configuration.web_logo` | `string` | The Web logo. |
| `theme_configuration.web_login_logo` | `string` | The Web login logo. |
| `theme_configuration.fav_icon` | `string` | The Fav icon. |
| `theme_configuration.accent_color` | `string` | The Accent color. |
| `client_session_timeout_in_seconds` | `uint32` | The client session timeout in seconds. |
| `dns_of_vaults_for_web[]` | repeated `string` | The list of Vault DNS for Web(vNext) which marked as Default Web Client. |
| `web_security_and_cors_settings` | [`SecurityAndCorsSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SecurityAndCorsSettings/index.md) | The Web Access Cross origin settings. |
| `web_security_and_cors_settings.enable_cross_origin_web_access[]` | repeated `string` | The cross origin domain access for classic web. |
| `web_security_and_cors_settings.cross_origin_headers` | `string` | The allowed cross-origin Header like Content-Type, X-Authentication, Access-Control-Allow-Origin. |
| `web_security_and_cors_settings.cross_origin_methods` | `string` | the allowed cross-origin Methods like PUT,POST,DELETE,GET. |
| `web_security_and_cors_settings.prevent_xfs` | `bool` | True to Prevent XFS, false to allow XFS. |
| `web_security_and_cors_settings.allowed_cross_frame_sites[]` | repeated `string` | The cross-frame sites access for classic web. |
| `classic_web_urlmigrate_settings` | [`NamedValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueArray/index.md) | Migrate classic web url settings. |
| `classic_web_urlmigrate_settings.value[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | An array of the NamedValue structures. |
| `classic_web_urlmigrate_settings.value[].key` | `string` | The name of the value. |
| `classic_web_urlmigrate_settings.value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `enable_web_link_migration_to_online_web` | `bool` | If true, migrate the web links to online web app(Account layer). |
| `custom_banner_configuration` | [`CustomBannerConfiguration`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CustomBannerConfiguration/index.md) | The custom banner configuration. |
| `custom_banner_configuration.color` | `string` | The background color. |
| `custom_banner_configuration.content[]` | repeated [`CustomBannerConfigurationContent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CustomBannerConfigurationContent/index.md) | Array of banner content. |
| `custom_banner_configuration.content[].type` | `string` | The type of the custom banner content. |
| `custom_banner_configuration.content[].text` | `string` | The text of the custom banner content. |
| `custom_banner_configuration.content[].value` | `string` | The value of the custom banner content. |
| `custom_banner_configuration.font_color` | `string` | The font color. |
| `custom_banner_configuration.font_family` | `string` | The font family. |
| `custom_banner_configuration.font_type` | `string` | The font type. |
| `idle_session_timeout_in_seconds` | `uint32` | The idle session timeout in seconds. |
---
# IRPCLogin.GetLicenseExpirationInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLicenseExpirationInfo/
Badges: `Vault API / core` `session` `session` `idempotent`
Gets the number of days until the server's license and its subscription expire.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetLicenseExpirationInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-license-expiration-info`
- **Request:** [`GetLicenseExpirationInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLicenseExpirationInfo/index.md#request)
- **Response:** [`GetLicenseExpirationInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLicenseExpirationInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to show license warnings; applications rarely need it.
## Request: GetLicenseExpirationInfoRequest
No fields.
## Response: GetLicenseExpirationInfoResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `license_is_always_valid` | `bool` | True if the license is always valid. |
| `license_expiration_time` | `int32` | Number of days until the license expires. Valid only if the license is not always valid. |
| `subscription_is_always_valid` | `bool` | True if the subscription is always valid. |
| `subscription_expiration_time` | `int32` | Number of days until the subscription expires. Valid only if the subscription is not always valid. |
---
# IRPCLogin.GetLoginSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLoginSettings/
Badges: `Vault API / core` `session` `no session`
Gets the anonymous login settings and enabled vertical applications of the vault that serves the
given host name, without a session.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetLoginSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-login-settings`
- **Request:** [`GetLoginSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLoginSettings/index.md#request)
- **Response:** [`GetLoginSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLoginSettings/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files login pages; applications rarely need it. `host_name_match` is false, and the
settings are empty, when no vault is configured for the host name.
## Request: GetLoginSettingsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `host_name` | `string` | If not empty, specifies the target hostname. |
## Response: GetLoginSettingsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `host_name_match` | `bool` | True if host name matches to the name provided when fetching these login settings. |
| `anonymous_login_settings` | [`AnonymousLoginSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AnonymousLoginSettings/index.md) | Receives the login settings. |
| `anonymous_login_settings.anonymous_login_allowed` | `bool` | True if anonymous login is allowed. |
| `vertical_applications` | [`VerticalApplications`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerticalApplications/index.md) | The vertical applications enabled for the vault. |
| `vertical_applications.v_tax_enabled` | `bool` | VTax vertical application is enabled for the vault. |
| `vertical_applications.v_con_enabled` | `bool` | VCon vertical application is enabled for the vault. |
| `vertical_applications.v_man_enabled` | `bool` | VMan vertical application is enabled for the vault. |
---
# IRPCLogin.GetPublicKey
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/
Badges: `Vault API / core` `session` `session` `idempotent`
Gets the server's RSA public key, for encrypting secrets that a client sends to the server.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetPublicKey`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-public-key`
- **Request:** [`GetPublicKeyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md#request)
- **Response:** [`GetPublicKeyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients that encrypt passwords or authentication data above the transport layer.
Over TLS, applications do not need it. The key is a Windows CryptoAPI public key blob.
## Request: GetPublicKeyRequest
> Nested 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) | Encryption for which the key is requested. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
## Response: GetPublicKeyResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `public_key` | `bytes` | Receives the public key as a BLOB. |
## Related methods
- [GetPublicKeyAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKeyAnonymous/index.md): Gets the server's RSA public key without a session, for encrypting authentication data before login.
---
# IRPCLogin.GetPublicKeyAnonymous
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKeyAnonymous/
Badges: `Vault API / core` `session` `no session`
Gets the server's RSA public key without a session, for encrypting authentication data before
login.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetPublicKeyAnonymous`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-public-key-anonymous`
- **Request:** [`GetPublicKeyAnonymousRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKeyAnonymous/index.md#request)
- **Response:** [`GetPublicKeyAnonymousResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKeyAnonymous/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Same key as [GetPublicKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md). Over TLS, applications do not
need it. Leave `remote_can_be_null` unset.
## Request: GetPublicKeyAnonymousRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `remote_can_be_null` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | If set, specifies the address of the remote server. |
| `remote_can_be_null.network_address` | `string` | The network address (name) of the server. |
| `remote_can_be_null.endpoint` | `string` | The endpoint of the server. |
| `remote_can_be_null.protocol_sequence` | `string` | The protocol sequence of the server. |
| `vault` | `string` | M-Files vault GUID. |
| `password_encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption for which the key is requested. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
## Response: GetPublicKeyAnonymousResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `public_key` | `bytes` | Receives the public key as a BLOB. |
## Related methods
- [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.
---
# IRPCLogin.GetRPCOverCOMInterface
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetRPCOverCOMInterface/
Badges: `Vault API / core` `session` `no session`
Gets RPC over COM interface for accessing M-Files Server.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetRPCOverCOMInterface`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-rpcover-cominterface`
- **Request:** [`GetRPCOverCOMInterfaceRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetRPCOverCOMInterface/index.md#request)
- **Response:** [`GetRPCOverCOMInterfaceResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetRPCOverCOMInterface/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Internal to M-Files on Windows (returns a marshalled COM interface). It is disabled by default and
then fails with `E_MFILES_ACCESS_DENIED`. Not usable by gRPC applications.
## Request: GetRPCOverCOMInterfaceRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `destination_context` | `uint32` | The destination context where the specified interface is to be unmarshaled. See the documentation of CoMarshalInterface. |
## Response: GetRPCOverCOMInterfaceResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `marshalled_interface` | `bytes` | Receives the marshalled interface. |
---
# IRPCLogin.GetVaultConnectionInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultConnectionInfo/
Badges: `Vault API / core` `session` `session`
Gets the full connection information of the current vault session, in the form the M-Files COM
API uses.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/GetVaultConnectionInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-connection-info`
- **Request:** [`GetVaultConnectionInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultConnectionInfo/index.md#request)
- **Response:** [`GetVaultConnectionInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultConnectionInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files components; applications should use
[GetVaultSessionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/index.md) and the `session_data`
returned at login instead. Requires a vault session. The RPC binding fields are left empty.
## Request: GetVaultConnectionInfoRequest
No fields.
## Response: GetVaultConnectionInfoResponse
> Nested message fields are expanded to depth 2 only, to keep the page small (the full expansion has more rows); follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `connection_info` | [`VaultConnectionInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultConnectionInfo/index.md) | The vault connection information of the user's session. |
| `connection_info.connection_mode` | [`MFilesAPIMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MFilesAPIMode/index.md) | The connection mode of M-Files API. Values: `MFILES_APIMODE_NORMAL` (0), `MFILES_APIMODE_INTERNAL_SERVER_ACCESS` (1), `MFILES_APIMODE_INTERNAL_SERVER_ACCESS_WITH_VAULT_MANAGEMENT` (2). |
| `connection_info.rpc_binding_string` | `string` | Binding string to the server. |
| `connection_info.minimum_rpc_authentication_level` | `uint32` | Ignored if connectionsecuritymode is specified. RPC_C_AUTHN_LEVEL_NONE or RPC_C_AUTHN_LEVEL_PKT_PRIVACY. Specifies the minimum authentication level to use if the protocol sequence is normal RPC, such as ncacn_ip_tcp. Ignored for other protocol sequences. |
| `connection_info.server_version` | `string` | Server version string (e.g. "10.0.3757" or "10.0.3757.0"). |
| `connection_info.client_computer_name` | `string` | The local computer name override used in the session. |
| `connection_info.vault_guid` | `string` | The GUID of the vault. |
| `connection_info.vault_display_name` | `string` | The name of the vault for display purposes. |
| `connection_info.locale_for_sorting` | `uint32` | Locale used for sorting. |
| `connection_info.session_id` | `bytes` | The session identifier. |
| `connection_info.session_info` | [`SessionInfoServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionInfoServer/index.md) | General session information. |
| `connection_info.attachment_guid` | `string` | The current attachment GUID of the vault. |
| `connection_info.enable_keep_alive` | `bool` | True to allow the keep-alive thread to run. |
| `connection_info.server_vault_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Capabilities of M-Files Server and the connected document vault. |
| `connection_info.client_capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | Capabilities of M-Files Client that were reported for the server when the connection (session) was established. |
| `connection_info.optional_grpc_cookies` | `string` | Optional cookie data for gRPC connections. May contain multiple "=" cookies separated by newline character. |
| `connection_info.server_data` | [`ServerData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerData/index.md) | Server data, including the product serial number and deployment type. Used to populate serial number and deployment type on SessionInfo. |
| `connection_info.connection_security_mode` | [`ConnectionSecurityMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConnectionSecurityMode/index.md) | Connection security mode. Overrides dwMinimumAuthenticationLevelIfNormalRPC if specified. Values: `CONNECTION_SECURITY_MODE_UNSPECIFIED` (0), `CONNECTION_SECURITY_MODE_NONE` (1), `CONNECTION_SECURITY_MODE_ENCRYPTED` (2), `CONNECTION_SECURITY_MODE_ENCRYPTED_IF_BUILTIN_KEY_AVAILABLE` (3). |
## Related methods
- [GetVaultSessionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetVaultSessionInfo/index.md): Gets basic information about the current vault session: server version and ID, vault GUID and name, and the state of the server push channel.
---
# IRPCLogin.IsServerRunningInEvaluationMode
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/IsServerRunningInEvaluationMode/
Badges: `Vault API / core` `session` `session` `idempotent`
Tells whether the server runs on an evaluation license, and how many evaluation days are left.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/IsServerRunningInEvaluationMode`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-server-running-in-evaluation-mode`
- **Request:** [`IsServerRunningInEvaluationModeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/IsServerRunningInEvaluationMode/index.md#request)
- **Response:** [`IsServerRunningInEvaluationModeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/IsServerRunningInEvaluationMode/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to show license warnings; applications rarely need it.
## Request: IsServerRunningInEvaluationModeRequest
No fields.
## Response: IsServerRunningInEvaluationModeResponse
> Nested 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` | True if the server runs on an evaluation license. |
| `evaluation_days_left` | `uint32` | Days left in the evaluation. Meaningful only when `evaluation_mode` is true. |
---
# IRPCLogin.LoginForAutomaticUpdates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LoginForAutomaticUpdates/
Badges: `Vault API / core` `session` `no session`
Logs in for automatic updates.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/LoginForAutomaticUpdates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/login-for-automatic-updates`
- **Request:** [`LoginForAutomaticUpdatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LoginForAutomaticUpdates/index.md#request)
- **Response:** [`LoginForAutomaticUpdatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LoginForAutomaticUpdates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
No longer supported: the server always fails this call. Software updates are not delivered by
M-Files Server.
## Request: LoginForAutomaticUpdatesRequest
> Nested 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 a client. This is used to determine a such suitable newer version for the client that is justified by the number. If unset, the latest software version is returned. |
| `password` | `string` | Automatic updates related password. If unset it's ignored. The primary purpose of this parameter is to refuse returning software updates to certain clients (e.g. M-Files and the password has been fall into other parties that want software updates). |
| `lang_identifier` | `string` | Language identifier (e.g. "eng" or "fin"). |
| `challenge` | `bytes` | The challenge to be used as an input for a digital signature algorithm. |
## Response: LoginForAutomaticUpdatesResponse
> Nested 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` | `bytes` | Session ID when the login process has been completed successfully. |
| `signature` | `bytes` | Receives the digital signature. |
---
# IRPCLogin.LogInRemote
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/
Badges: `Vault API / core` `session` `no session`
Logs in (with authentication) to a remote server.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/LogInRemote`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/log-in-remote`
- **Request:** [`LogInRemoteRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/index.md#request)
- **Response:** [`LogInRemoteResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInRemote/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files cached replica vaults to log in to the main server. Disabled by default; then the
call fails with `E_MFILES_CONFIGURING_REPLICA_VAULTS_NOT_ALLOWED`. Not for applications.
## Request: LogInRemoteRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `remote_server_addr` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the remote server. |
| `remote_server_addr.network_address` | `string` | The network address (name) of the server. |
| `remote_server_addr.endpoint` | `string` | The endpoint of the server. |
| `remote_server_addr.protocol_sequence` | `string` | The protocol sequence of the server. |
| `environment_data` | [`EnvironmentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EnvironmentData/index.md) | Description of the client environment. |
| `environment_data.client_name` | `string` | A name for the client device, such as its host name. Shown as the session's computer name. Must not start with `@{`. |
| `environment_data.timezone` | [`TimeZoneInformation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TimeZoneInformation/index.md) | The client device's time zone. Leave unset if unknown. |
| `environment_data.timezone.bias_in_minutes` | `int32` | The difference between UTC and local time, in minutes. |
| `environment_data.timezone.standard_name` | `string` | A description for standard time, max length 31. |
| `environment_data.timezone.standard_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from daylight saving time to standard time occurs. |
| `environment_data.timezone.standard_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during standard time. |
| `environment_data.timezone.daylight_name` | `string` | A description for daylight saving time (DST), max length 31. |
| `environment_data.timezone.daylight_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from standard time to daylight saving time occurs. |
| `environment_data.timezone.daylight_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during daylight saving time. |
| `environment_data.host_platform` | `string` | Free-form description of the platform, for example `Windows 11` or `Python 3.13`. |
| `environment_data.device_token` | `string` | A stable, globally unique identifier of the device. Used by M-Files clients that register devices; see [DisconnectDevice](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md). |
| `client_data` | [`ClientData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientData/index.md) | Description of the client. |
| `client_data.version` | `uint64` | The client's version, packed like `QueryVersionResponse.server_version` (`major << 48 \| minor << 32 \| build << 16 \| patch`). May be 0. If the server administrator has set a minimum client version, older clients are refused with `E_MFILES_INCOMPATIBLE_SERVER_VERSION`. |
| `client_data.capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | Features the client software handles. The server adapts some responses to them, so set only the flags your code implements; leave the rest false. |
| `client_data.capabilities.property_def_searchability` | `bool` | Property definitions can be configured searchable or unsearchable. |
| `client_data.capabilities.unmanaged_objects` | `bool` | Client understands unmanaged objects. |
| `client_data.capabilities.extension_authentication_data_push` | `bool` | Client supports data push for extension authentications. |
| `client_data.capabilities.custom_api_data_push` | `bool` | Client supports server data push for M-Files API & custom implementations. |
| `client_data.capabilities.unknown_file_size` | `bool` | Client can handle unknown or estimated file size. |
| `client_data.capabilities.typed_metadata_suggestions` | `bool` | Client can handle metadata suggestions to all M-Files types. |
| `client_data.capabilities.long_authentication_attempt_identifier` | `bool` | The client handles the long (32-byte) authentication attempt identifier in `AuthenticationAttemptIdentifier.data`. |
| `client_data.capabilities.reverse_grouping_level` | `bool` | Client supports reverse grouping levels. |
| `client_data.capabilities.object_permissions_for_client` | `bool` | Client supports ObjectPermissionsForClient. |
| `client_data.capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `client_data.capabilities.smart_search` | `bool` | Client supports Smart Search engine type. |
| `client_data.capabilities.recurring_notifications` | `bool` | Client supports recurring notifications. |
| `client_data.capabilities.smart_search_facets` | `bool` | Client supports smart search facets. |
| `client_data.capabilities.vault_role_manage_private_views` | `bool` | Client supports a vault role for managing private views. |
| `client_data.capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Client supports that all users can see deleted conflict objects. |
| `client_data.capabilities.advanced_password_hashes` | `bool` | Client supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `client_data.capabilities.anonymous_authentication` | `bool` | Client supports anonymous authentication. |
| `client_data.capabilities.dataset_deleted_condition` | `bool` | Client supports deleted/not deleted-condition in a dataset definition. |
| `client_data.capabilities.unified_password_hashes` | `bool` | Client supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `client_data.capabilities.duplicates_view` | `bool` | Client supports the duplicates view. |
| `client_data.capabilities.property_action_state_transition_time` | `bool` | Client supports state transition time setting via state property action. |
| `client_data.capabilities.at_mentions` | `bool` | Client supports the @mentions in comment texts. |
| `client_data.capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Client supports additive permissions via automatic ACL components. |
| `client_data.capabilities.vault_level_optimization_jobs` | `bool` | Client supports vault-level optimization jobs. |
| `client_data.capabilities.visitor_links_supported` | `bool` | Client supports new interface methods for visitor links. |
| `client_data.capabilities.object_type_filter_multi_select_views` | `bool` | Client supports multiple object types as a filter for views and advanced searches. |
| `client_data.capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Client supports generating authentication configuration for Azure v2.0 endpoint. |
| `client_data.capabilities.structure_item_groups_in_export` | `bool` | Client supports structure item groups in the export job. |
| `client_data.capabilities.aino_search` | `bool` | Client supports Aino Search engine type. |
| `client_data.capabilities.conversation_history` | `bool` | Client supports conversation history. |
| `client_data.capabilities.generate_login_service_auth_conf` | `bool` | Client supports generating authentication configuration for M-Files Login Service. |
| `client_data.capabilities.sub_folders_in_views` | `bool` | Client supports subfolders in views. |
| `client_data.capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Client supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `client_data.capabilities.entity_version_checking_supported` | `bool` | Client supports entity version numbering to track modification conflicts. |
| `client_data.capabilities.workflow_descriptions_supported` | `bool` | Client supports workflow descriptions. |
| `client_data.capabilities.property_value_metadata_supported` | `bool` | Client supports setting and retrieving property value metadata. |
| `client_data.capabilities.object_type_grouping_for_relationships` | `bool` | Client supports object type based grouping for relationships. |
| `client_data.capabilities.draft_objects` | `bool` | Client supports draft objects in discovery results. |
| `client_data.language` | `string` | The client's language, for example `en`. For [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md), empty means the language of the existing session. |
| `client_data.type` | [`ClientType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ClientType/index.md) | The kind of client. Applications use `CLIENT_TYPE_SERVER_API`. |
| `client_data.type_specifier` | `string` | Optional free-form name of the client application. |
| `login_data` | [`LoginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LoginData/index.md) | Description of the desired login. |
| `login_data.server_hostname` | `string` | The host name the client used to reach the server. Optional for user name and password logins. Anonymous logins, and server-level logins on servers with vault login accounts, use it to find the vault configured for that host name. |
| `login_data.vault_guid` | `string` | The vault to log in to, as a GUID string with or without braces, in any case. Use `{00000000-0000-0000-0000-000000000000}` for a server-level session; an empty string is rejected with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. |
| `login_data.is_administrative` | `bool` | True for administrative tools that manage the vault rather than work with documents, as M-Files Admin does. Applications leave it false. |
| `login_data.client_session_timeout_in_seconds` | `uint32` | Optional. Requests a longer idle timeout for a vault session. Honored only when it is at least the server's session timeout and at most 7 days (or the server timeout if that is longer); otherwise, and for server-level sessions, the server timeout applies. The effective value shows as `SessionData.keep_alive_interval_in_seconds`, which is half of it. |
| `authentication_data` | [`AuthDataClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClient/index.md) | Authentication data for the remote server, as in `LogIn`. |
| `authentication_data.type` | [`AuthDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthDataType/index.md) | The authentication method. Must match the member set in `data`; unset fails with `E_INVALIDARG`. For user name and password use `AUTH_DATA_TYPE_CREDENTIALS`. Values: `AUTH_DATA_TYPE_UNDEFINED` (0), `AUTH_DATA_TYPE_MFILES_LEG1` (1), `AUTH_DATA_TYPE_MFILES_LEG2` (2), `AUTH_DATA_TYPE_WINDOWS` (3), `AUTH_DATA_TYPE_PLUGIN` (4), `AUTH_DATA_TYPE_CREDENTIALS` (5), `AUTH_DATA_TYPE_ANONYMOUS` (6). |
| `authentication_data.data` | [`AuthDataClientUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md) | The method's data. Set exactly the member that `type` names. |
| `authentication_data.data.mfiles_leg1` | [`AuthDataClientUnion.MFilesLeg1Data`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-MFilesLeg1Data) (oneof data) | First call of the two-step M-Files challenge login (`AUTH_DATA_TYPE_MFILES_LEG1`). |
| `authentication_data.data.mfiles_leg2` | [`AuthDataClientUnion.MFilesLeg2Data`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-MFilesLeg2Data) (oneof data) | Second call of the two-step M-Files challenge login (`AUTH_DATA_TYPE_MFILES_LEG2`). |
| `authentication_data.data.windows` | [`AuthDataClientUnion.WindowsData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-WindowsData) (oneof data) | Windows authentication tokens (`AUTH_DATA_TYPE_WINDOWS`), possibly over several calls. |
| `authentication_data.data.plugin` | [`AuthDataClientUnion.PluginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-PluginData) (oneof data) | Authentication through a plug-in such as single sign-on (`AUTH_DATA_TYPE_PLUGIN`). |
| `authentication_data.data.credentials` | [`Credentials`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Credentials/index.md) (oneof data) | User name and password (`AUTH_DATA_TYPE_CREDENTIALS`). Completes in one call. |
| `authentication_data.data.anonymous` | [`AuthDataClientUnion.AnonymousData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataClientUnion/index.md#t-AnonymousData) (oneof data) | Anonymous login (`AUTH_DATA_TYPE_ANONYMOUS`), when the vault allows it. Has no data. |
| `authentication_data.certificate_proof` | `string` | Leave empty. Used only when the server requires client certificates. |
| `authentication_data.is_certificate_validated` | `bool` | Leave false. Set only by M-Files proxies that validate client certificates themselves. |
## Response: LogInRemoteResponse
> Nested message fields are expanded to depth 2 only, to keep the page small (the full expansion has more rows); follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `authentication_data` | [`AuthDataServer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataServer/index.md) | The remote server's part of the authentication exchange, as in `LogIn`. |
| `authentication_data.type` | [`AuthDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AuthDataType/index.md) | The authentication method, as in the request. Values: `AUTH_DATA_TYPE_UNDEFINED` (0), `AUTH_DATA_TYPE_MFILES_LEG1` (1), `AUTH_DATA_TYPE_MFILES_LEG2` (2), `AUTH_DATA_TYPE_WINDOWS` (3), `AUTH_DATA_TYPE_PLUGIN` (4), `AUTH_DATA_TYPE_CREDENTIALS` (5), `AUTH_DATA_TYPE_ANONYMOUS` (6). |
| `authentication_data.data` | [`AuthDataServerUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthDataServerUnion/index.md) | Method-specific reply: a challenge, a token to pass on, or nothing. |
| `authentication_data.authentication_attempt_identifier` | [`AuthenticationAttemptIdentifier`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthenticationAttemptIdentifier/index.md) | Identifies this login attempt. In multi-step methods, send it back in the next call, in the `authentication_attempt_identifier` field of the request's union member. Ignore it for `AUTH_DATA_TYPE_CREDENTIALS`. |
| `session_data` | [`SessionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionData/index.md) | Description of the created session when login is complete, or unset otherwise. |
| `session_data.session_id` | `bytes` | The session ID (48 bytes). Send it unchanged in the `mfiles-session-id-bin` metadata header of every call that needs a session. |
| `session_data.account_name` | `string` | The login account name, with the case stored on the server. |
| `session_data.access_rights` | [`SessionAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionAccess/index.md) | What the session may do on server level and in the vault, regardless of object permissions. |
| `session_data.server_vault_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Capabilities of the server and, for vault sessions, the vault, as they apply to this user. More precise than [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md). |
| `session_data.locale` | `uint32` | The Windows locale ID used for sorting, for example 1033. |
| `session_data.keep_alive_interval_in_seconds` | `uint32` | Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) at least this often. It is half of the session's idle timeout. |
| `session_data.use_strict_set_equality_comparison` | `bool` | If false, not equal type comparisons are performed in pre-MF11 style in which it is enough that at least one of the left-side values does not match any of the right-side values in order to treat the left and right values unequal. If true, none of the left-side values can match any of the right-side values in order to treat the left and right values unequal i.e. pure set-based exclusion. Prefer using the new comparison style. The old behavior is provided for compatibility reasons. |
| `session_data.product_mode` | [`ProductMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ProductMode/index.md) | The edition of the server license. Values: `PRODUCT_MODE_FULL` (0), `PRODUCT_MODE_EXPRESS` (1), `PRODUCT_MODE_BUSINESS` (2). |
| `session_data.vault_data` | [`VaultData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultData/index.md) | The user's identity in the vault. Unset for a server-level session. |
| `session_data.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Whether the login account is an M-Files or a Windows account. Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `session_data.server_data` | [`ServerData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerData/index.md) | The server's license serial number and deployment type. |
| `session_data.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license the session uses. 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). |
| `session_data.keep_upload_session_alive_interval_in_seconds` | `uint32` | Keep a file upload session alive at least this often (half of the upload session timeout). |
## Related methods
- [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
---
# IRPCLogin.Relogin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/Relogin/
Badges: `Vault API / core` `session` `session`
Logs in again by using the current session ID. Used by M-Files' own clients.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/Relogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/relogin`
- **Request:** [`ReloginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/Relogin/index.md#request)
- **Response:** [`ReloginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/Relogin/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Applications do not need this method: when a call answers `UNAUTHENTICATED`, log in again with
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md). Works only for vault sessions; a logged-out session is
refused.
## Request: ReloginRequest
> Nested 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 session (`session_data.account_name`). |
| `environment_data` | [`EnvironmentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EnvironmentData/index.md) | Describes the client device, as in `LogIn`. |
| `environment_data.client_name` | `string` | A name for the client device, such as its host name. Shown as the session's computer name. Must not start with `@{`. |
| `environment_data.timezone` | [`TimeZoneInformation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TimeZoneInformation/index.md) | The client device's time zone. Leave unset if unknown. |
| `environment_data.timezone.bias_in_minutes` | `int32` | The difference between UTC and local time, in minutes. |
| `environment_data.timezone.standard_name` | `string` | A description for standard time, max length 31. |
| `environment_data.timezone.standard_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from daylight saving time to standard time occurs. |
| `environment_data.timezone.standard_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during standard time. |
| `environment_data.timezone.daylight_name` | `string` | A description for daylight saving time (DST), max length 31. |
| `environment_data.timezone.daylight_date` | [`SystemTime`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SystemTime/index.md) | The local date and time when the transition from standard time to daylight saving time occurs. |
| `environment_data.timezone.daylight_bias_in_minutes` | `int32` | This value is added to the value of the lBias member to form the bias used during daylight saving time. |
| `environment_data.host_platform` | `string` | Free-form description of the platform, for example `Windows 11` or `Python 3.13`. |
| `environment_data.device_token` | `string` | A stable, globally unique identifier of the device. Used by M-Files clients that register devices; see [DisconnectDevice](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/DisconnectDevice/index.md). |
| `client_data` | [`ClientData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientData/index.md) | Describes the client software, as in `LogIn`. |
| `client_data.version` | `uint64` | The client's version, packed like `QueryVersionResponse.server_version` (`major << 48 \| minor << 32 \| build << 16 \| patch`). May be 0. If the server administrator has set a minimum client version, older clients are refused with `E_MFILES_INCOMPATIBLE_SERVER_VERSION`. |
| `client_data.capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | Features the client software handles. The server adapts some responses to them, so set only the flags your code implements; leave the rest false. |
| `client_data.capabilities.property_def_searchability` | `bool` | Property definitions can be configured searchable or unsearchable. |
| `client_data.capabilities.unmanaged_objects` | `bool` | Client understands unmanaged objects. |
| `client_data.capabilities.extension_authentication_data_push` | `bool` | Client supports data push for extension authentications. |
| `client_data.capabilities.custom_api_data_push` | `bool` | Client supports server data push for M-Files API & custom implementations. |
| `client_data.capabilities.unknown_file_size` | `bool` | Client can handle unknown or estimated file size. |
| `client_data.capabilities.typed_metadata_suggestions` | `bool` | Client can handle metadata suggestions to all M-Files types. |
| `client_data.capabilities.long_authentication_attempt_identifier` | `bool` | The client handles the long (32-byte) authentication attempt identifier in `AuthenticationAttemptIdentifier.data`. |
| `client_data.capabilities.reverse_grouping_level` | `bool` | Client supports reverse grouping levels. |
| `client_data.capabilities.object_permissions_for_client` | `bool` | Client supports ObjectPermissionsForClient. |
| `client_data.capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `client_data.capabilities.smart_search` | `bool` | Client supports Smart Search engine type. |
| `client_data.capabilities.recurring_notifications` | `bool` | Client supports recurring notifications. |
| `client_data.capabilities.smart_search_facets` | `bool` | Client supports smart search facets. |
| `client_data.capabilities.vault_role_manage_private_views` | `bool` | Client supports a vault role for managing private views. |
| `client_data.capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Client supports that all users can see deleted conflict objects. |
| `client_data.capabilities.advanced_password_hashes` | `bool` | Client supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `client_data.capabilities.anonymous_authentication` | `bool` | Client supports anonymous authentication. |
| `client_data.capabilities.dataset_deleted_condition` | `bool` | Client supports deleted/not deleted-condition in a dataset definition. |
| `client_data.capabilities.unified_password_hashes` | `bool` | Client supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `client_data.capabilities.duplicates_view` | `bool` | Client supports the duplicates view. |
| `client_data.capabilities.property_action_state_transition_time` | `bool` | Client supports state transition time setting via state property action. |
| `client_data.capabilities.at_mentions` | `bool` | Client supports the @mentions in comment texts. |
| `client_data.capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Client supports additive permissions via automatic ACL components. |
| `client_data.capabilities.vault_level_optimization_jobs` | `bool` | Client supports vault-level optimization jobs. |
| `client_data.capabilities.visitor_links_supported` | `bool` | Client supports new interface methods for visitor links. |
| `client_data.capabilities.object_type_filter_multi_select_views` | `bool` | Client supports multiple object types as a filter for views and advanced searches. |
| `client_data.capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Client supports generating authentication configuration for Azure v2.0 endpoint. |
| `client_data.capabilities.structure_item_groups_in_export` | `bool` | Client supports structure item groups in the export job. |
| `client_data.capabilities.aino_search` | `bool` | Client supports Aino Search engine type. |
| `client_data.capabilities.conversation_history` | `bool` | Client supports conversation history. |
| `client_data.capabilities.generate_login_service_auth_conf` | `bool` | Client supports generating authentication configuration for M-Files Login Service. |
| `client_data.capabilities.sub_folders_in_views` | `bool` | Client supports subfolders in views. |
| `client_data.capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Client supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `client_data.capabilities.entity_version_checking_supported` | `bool` | Client supports entity version numbering to track modification conflicts. |
| `client_data.capabilities.workflow_descriptions_supported` | `bool` | Client supports workflow descriptions. |
| `client_data.capabilities.property_value_metadata_supported` | `bool` | Client supports setting and retrieving property value metadata. |
| `client_data.capabilities.object_type_grouping_for_relationships` | `bool` | Client supports object type based grouping for relationships. |
| `client_data.capabilities.draft_objects` | `bool` | Client supports draft objects in discovery results. |
| `client_data.language` | `string` | The client's language, for example `en`. For [LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md), empty means the language of the existing session. |
| `client_data.type` | [`ClientType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ClientType/index.md) | The kind of client. Applications use `CLIENT_TYPE_SERVER_API`. |
| `client_data.type_specifier` | `string` | Optional free-form name of the client application. |
| `login_data` | [`LoginData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LoginData/index.md) | Must name the vault of the session in `vault_guid`. |
| `login_data.server_hostname` | `string` | The host name the client used to reach the server. Optional for user name and password logins. Anonymous logins, and server-level logins on servers with vault login accounts, use it to find the vault configured for that host name. |
| `login_data.vault_guid` | `string` | The vault to log in to, as a GUID string with or without braces, in any case. Use `{00000000-0000-0000-0000-000000000000}` for a server-level session; an empty string is rejected with `E_MFILES_INVALID_VAULT_GUID_X_DESC`. |
| `login_data.is_administrative` | `bool` | True for administrative tools that manage the vault rather than work with documents, as M-Files Admin does. Applications leave it false. |
| `login_data.client_session_timeout_in_seconds` | `uint32` | Optional. Requests a longer idle timeout for a vault session. Honored only when it is at least the server's session timeout and at most 7 days (or the server timeout if that is longer); otherwise, and for server-level sessions, the server timeout applies. The effective value shows as `SessionData.keep_alive_interval_in_seconds`, which is half of it. |
## Response: ReloginResponse
> Nested message fields are expanded to depth 2 only, to keep the page small (the full expansion has more rows); follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `session_data` | [`SessionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionData/index.md) | The session. Use its `session_id` from now on. |
| `session_data.session_id` | `bytes` | The session ID (48 bytes). Send it unchanged in the `mfiles-session-id-bin` metadata header of every call that needs a session. |
| `session_data.account_name` | `string` | The login account name, with the case stored on the server. |
| `session_data.access_rights` | [`SessionAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SessionAccess/index.md) | What the session may do on server level and in the vault, regardless of object permissions. |
| `session_data.server_vault_capabilities` | [`ServerVaultCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md) | Capabilities of the server and, for vault sessions, the vault, as they apply to this user. More precise than [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md). |
| `session_data.locale` | `uint32` | The Windows locale ID used for sorting, for example 1033. |
| `session_data.keep_alive_interval_in_seconds` | `uint32` | Call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md) at least this often. It is half of the session's idle timeout. |
| `session_data.use_strict_set_equality_comparison` | `bool` | If false, not equal type comparisons are performed in pre-MF11 style in which it is enough that at least one of the left-side values does not match any of the right-side values in order to treat the left and right values unequal. If true, none of the left-side values can match any of the right-side values in order to treat the left and right values unequal i.e. pure set-based exclusion. Prefer using the new comparison style. The old behavior is provided for compatibility reasons. |
| `session_data.product_mode` | [`ProductMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ProductMode/index.md) | The edition of the server license. Values: `PRODUCT_MODE_FULL` (0), `PRODUCT_MODE_EXPRESS` (1), `PRODUCT_MODE_BUSINESS` (2). |
| `session_data.vault_data` | [`VaultData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultData/index.md) | The user's identity in the vault. Unset for a server-level session. |
| `session_data.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Whether the login account is an M-Files or a Windows account. Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `session_data.server_data` | [`ServerData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerData/index.md) | The server's license serial number and deployment type. |
| `session_data.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license the session uses. 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). |
| `session_data.keep_upload_session_alive_interval_in_seconds` | `uint32` | Keep a file upload session alive at least this often (half of the upload session timeout). |
## Related methods
- [LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
---
# IRPCLogin.ResolveMaturityOfFeature
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ResolveMaturityOfFeature/
Badges: `Vault API / core` `session` `no session`
Returns which of the named server feature flags are enabled on this server.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/ResolveMaturityOfFeature`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/resolve-maturity-of-feature`
- **Request:** [`ResolveMaturityOfFeatureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ResolveMaturityOfFeature/index.md#request)
- **Response:** [`ResolveMaturityOfFeatureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/ResolveMaturityOfFeature/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to align their behavior with the server; applications rarely need it.
Unknown flag names are left out of the response.
## Request: ResolveMaturityOfFeatureRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `feature_flags[]` | repeated `string` | FeatureFlags to be resolved. |
## Response: ResolveMaturityOfFeatureResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `matured_feature_flags[]` | repeated `string` | Receives the list of matured feature flags. |
---
# IRPCLogin.SetOpenSessionCheck
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/SetOpenSessionCheck/
Badges: `Vault API / core` `session` `session`
Sets whether administrators are warned about this session when they take the vault offline or do
other maintenance.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/SetOpenSessionCheck`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-open-session-check`
- **Request:** [`SetOpenSessionCheckRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/SetOpenSessionCheck/index.md#request)
- **Response:** [`SetOpenSessionCheckResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/SetOpenSessionCheck/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Sessions are included in the check by default. A background service that can safely be
disconnected may turn it off. Has no effect on what the session can do.
## Request: SetOpenSessionCheckRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `make_open_session_check` | `bool` | True if the check is made (default). If the check is disabled the administrator does not get a warning that this session is open when the vault is set to offline mode for example. |
## Response: SetOpenSessionCheckResponse
No fields.
---
# IRPCLogin.VerifyLicenseSubscriptionTime
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/VerifyLicenseSubscriptionTime/
Badges: `Vault API / core` `session` `no session`
Fails if the server's license subscription has expired; succeeds otherwise.
- **Service:** [Login and sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/index.md) `MFiles.IRPCLogin`
- **gRPC method:** `/MFiles.IRPCLogin/VerifyLicenseSubscriptionTime`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/verify-license-subscription-time`
- **Request:** [`VerifyLicenseSubscriptionTimeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/VerifyLicenseSubscriptionTime/index.md#request)
- **Response:** [`VerifyLicenseSubscriptionTimeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/VerifyLicenseSubscriptionTime/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** session
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. Used by M-Files clients; applications rarely need it.
## Request: VerifyLicenseSubscriptionTimeRequest
No fields.
## Response: VerifyLicenseSubscriptionTimeResponse
No fields.
---
# Vaults on a server (IRPCVaults)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/
An interface for enumerating vaults.
Use this interface to get a listing of registered vaults on the server.
- **gRPC service:** `MFiles.IRPCVaults`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCVaults.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaults.proto)
## Overview
Lists the vaults on the server that the logged-in user can see. Use it to let a user pick a vault
or to find a vault's GUID by its name; then log in to that vault with
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) or
[LogInWithSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogInWithSession/index.md).
[GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md) is the method to use. It accepts both a
server-level session (from a `LogIn` with the all-zero vault GUID) and a vault session.
`GetReplicasOfVaults` and `GetGroundLinkProxies` serve special deployments and return nothing on
an ordinary server. Server-level and vault sessions are described in
[Authentication and sessions](https://developer.m-files.com/APIs/gRPC-API/runtime/authentication/index.md).
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md) | Lists the vaults on the server that the session's user can see. | `read` `session` `idempotent` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [GetGroundLinkProxies](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetGroundLinkProxies/index.md) | Lists the Ground Link proxy vaults on the server that the session's user can see. | `read` `session` `idempotent` |
| [GetReplicasOfVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetReplicasOfVaults/index.md) | Gets replicas of document vaults (links to (remote) document vaults). | `write` `no session` |
---
# IRPCVaults.GetVaults
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/
Badges: `Vault API / core` `read` `session` `idempotent`
Lists the vaults on the server that the session's user can see.
- **Service:** [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md) `MFiles.IRPCVaults`
- **gRPC method:** `/MFiles.IRPCVaults/GetVaults`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vaults`
- **Request:** [`GetVaultsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md#request)
- **Response:** [`GetVaultsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Requires a session, either server-level or vault-level; without one the call fails with
`UNAUTHENTICATED`.
Which vaults are returned:
- A user who can manage vaults on the server sees every vault, unless
`exclude_vaults_user_cannot_access` is true.
- Any other user sees only vaults where the login account has a user account. With
`exclude_vaults_user_cannot_access` the user account must also be allowed to log in.
- A user whose login account lives in one vault (vault login accounts) sees only that vault.
- Offline vaults are left out unless `include_offline_vaults` is true.
`vaults` and `online_states` are parallel arrays: `online_states[i]` is the state of `vaults[i]`.
## Request: GetVaultsRequest
A structure that specifies get vaults 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 |
|---|---|---|
| `include_offline_vaults` | `bool` | True to also return vaults that are offline. Default false: only online vaults. |
| `exclude_vaults_user_cannot_access` | `bool` | True to return only vaults the user can log in to. Without it a non-administrator also sees vaults where the user account exists but cannot log in, and a user who manages vaults sees all vaults. |
## Response: GetVaultsResponse
A structure that specifies get vaults 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 |
|---|---|---|
| `vaults[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | The visible vaults. `guid` is the value to pass in `LoginData.vault_guid`. |
| `vaults[].guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vaults[].display_name` | `string` | The vault name shown to users. |
| `vaults[].tooltip` | `string` | Optional description. Often empty. |
| `vaults[].icon` | `bytes` | The vault icon in .ico format, or empty. |
| `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. |
| `vaults[].dns_names.value[]` | repeated `string` | String values. |
| `online_states[]` | repeated `bool` | True if the vault at the same index in `vaults` is online. |
---
# IRPCVaults.GetGroundLinkProxies
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetGroundLinkProxies/
Badges: `Vault API / core` `read` `session` `idempotent`
Lists the Ground Link proxy vaults on the server that the session's user can see.
- **Service:** [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md) `MFiles.IRPCVaults`
- **gRPC method:** `/MFiles.IRPCVaults/GetGroundLinkProxies`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-ground-link-proxies`
- **Request:** [`GetGroundLinkProxiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetGroundLinkProxies/index.md#request)
- **Response:** [`GetGroundLinkProxiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetGroundLinkProxies/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files components that work with Ground Link; applications rarely need it. Visibility
and `online_states` work as in [GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md). The response is
empty on a server without Ground Link proxies.
## Request: GetGroundLinkProxiesRequest
A structure that specifies get ground link proxies 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 |
|---|---|---|
| `include_offline_vaults` | `bool` | True to also return proxies that are offline. |
## Response: GetGroundLinkProxiesResponse
A structure that specifies get ground link proxies 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 |
|---|---|---|
| `vaults[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | The visible Ground Link proxy vaults. |
| `vaults[].guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vaults[].display_name` | `string` | The vault name shown to users. |
| `vaults[].tooltip` | `string` | Optional description. Often empty. |
| `vaults[].icon` | `bytes` | The vault icon in .ico format, or empty. |
| `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. |
| `vaults[].dns_names.value[]` | repeated `string` | String values. |
| `online_states[]` | repeated `bool` | True if the proxy at the same index in `vaults` is online. |
## Related methods
- [GetVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetVaults/index.md): Lists the vaults on the server that the session's user can see.
---
# IRPCVaults.GetReplicasOfVaults
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetReplicasOfVaults/
Badges: `Vault API / core` `write` `no session`
Gets replicas of document vaults (links to (remote) document vaults).
- **Service:** [Vaults on a server](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md) `MFiles.IRPCVaults`
- **gRPC method:** `/MFiles.IRPCVaults/GetReplicasOfVaults`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-replicas-of-vaults`
- **Request:** [`GetReplicasOfVaultsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetReplicasOfVaults/index.md#request)
- **Response:** [`GetReplicasOfVaultsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/GetReplicasOfVaults/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files cached replica vaults over MS-RPC. Over gRPC the response is always empty.
## Request: GetReplicasOfVaultsRequest
A structure that specifies get replicas of vaults request.
No fields.
## Response: GetReplicasOfVaultsResponse
A structure that specifies get replicas of vaults 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 |
|---|---|---|
| `vaults[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Always empty over gRPC. |
| `vaults[].guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vaults[].display_name` | `string` | The vault name shown to users. |
| `vaults[].tooltip` | `string` | Optional description. Often empty. |
| `vaults[].icon` | `bytes` | The vault icon in .ico format, or empty. |
| `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. |
| `vaults[].dns_names.value[]` | repeated `string` | String values. |
---
# Vault information (IRPCVault)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/
An interface for vault-level information and operations.
Provides methods for miscellaneous vault-level operations.
- **gRPC service:** `MFiles.IRPCVault`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 26
- **Proto file:** [`mfiles/IRPCVault.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVault.proto)
## Overview
Vault-level lookups that most applications need right after login: the vault's own identity,
turning stable identifiers (GUIDs and aliases) into the vault's numeric IDs, listing users and
user groups, and detecting changes to the metadata structure.
All methods need a vault session (`LogIn` with a vault GUID); a server-level session fails with
`E_MFILES_LOGIN_REQUIRED`.
| Job | Methods |
|---|---|
| Which vault am I in? | `GetVault` |
| Resolve a GUID to an ID | `GetMetadataStructureItemIdByGUID` |
| Resolve an alias to an ID | `GetMetadataStructureItemIdByAlias`, `GetAllMetadataStructureItemIdswithAliases`, `GetMetadataStructureItemIdsByAliases` |
| List users and groups | `GetUsersAndUserContainers`, `GetUsersAndUserGroupsList`, `GetUsersAndUserGroups` |
| Groups of a user | `GetGroupsOfUserOrGroup` |
| Has the structure changed? | `GetMetadataStructureVersion` |
**IDs are per vault.** Object types, property definitions, classes, workflows, states and other
structure items get their numeric IDs from the vault, so the same item can have different IDs in
different vaults. Resolve them at run time from a GUID or an alias (set by the vault
administrator) instead of hard-coding IDs, and cache the result together with the metadata
structure version.
**Caching.** Most methods return the vault's metadata structure version in the
`mfiles-metadata-version-bin` trailer (4 bytes, a little-endian `int32`). When the number changes,
cached structure lookups are stale. Call
[GetMetadataStructureVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md) to check it
without other work. See
[Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md)
and, for aliases and GUIDs,
[Vault and metadata structure](https://developer.m-files.com/APIs/gRPC-API/concepts/vault-and-metadata-structure/index.md).
**JSON in `bytes` fields.** `GetUsersAndUserGroups`, the `...OrDelta` methods and
`GetMetadataStructureItemIdsByAliases*` return JSON text in `bytes` fields, zlib-compressed unless
the matching length field is 4294967295. Prefer the typed alternatives named in each method.
Server push (`SendPushDataResponse`, `SendPushDataPendingHeartbeat`, `NotifyDataPushEvent`) and
multi-server methods (`GetVaultServerAttachments`, `GetServerRoles`, `BroadcastRequest`) are for
M-Files' own clients and servers.
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [GetVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVault/index.md) | Gets the GUID, display name and other basic data of the session's vault. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMetadataStructureItemIdByAlias](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/index.md) | Finds the vault-specific ID of a metadata structure item from one of its aliases. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMetadataStructureItemIdsByAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md) | Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as JSON. | `write` `session or assertion` `returns metadata structure version` |
| [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md) | Finds the vault-specific ID of a metadata structure item (object type, property definition, class, workflow, ...) from its GUID. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetUsersAndUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md) | Gets all users and normal user groups of the vault as JSON. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMetadataStructureVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md) | Gets the version numbers of the vault's metadata structure and of its property definitions. | `read` `session or assertion` `idempotent` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [BroadcastRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/BroadcastRequest/index.md) | Broadcasts a vault level request. | `write` `session` `idempotent` `returns metadata structure version` |
| [GetAllMetadataStructureItemIdswithAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md) | Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as typed lists. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetAllTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllTranslations/index.md) | Gets all translations of the vault's metadata structure names as one JSON document. | `write` `session or assertion` `returns metadata structure version` |
| [GetGroupsOfUserOrGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetGroupsOfUserOrGroup/index.md) | Gets the user groups that a user or a user group belongs to. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md) | Gets the vault's real object types (not value lists), with icons, in one call. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMetadataStructureItemIdsByAliases_Compressed](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed/index.md) | Gets alias-to-ID mappings of several kinds of metadata structure item as JSON, with the option to exclude kinds. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMetadataStructureItemIdsFromMDCardConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsFromMDCardConfiguration/index.md) | Gets metadata structure item IDs and related aliases or GUIDs which are used in Metadata card configuration value. Created for HttpServer. | `write` `session or assertion` `returns metadata structure version` |
| [GetReportAccessCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetReportAccessCredentials/index.md) | Gets the report access credentials for this vault. The credentials are encrypted with the provided public key. | `read` `session` `idempotent` `returns metadata structure version` |
| [GetServerRoles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetServerRoles/index.md) | Gets the multi-server roles this server has with the vault. | `read` `session` `idempotent` |
| [GetUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserContainers/index.md) | Gets all user groups of the vault, of all group types, with their members. | `write` `session or assertion` `returns metadata structure version` |
| [GetUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroup/index.md) | Gets one user group with its members. | `write` `session or assertion` `returns metadata structure version` |
| [GetUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md) | Gets the vault's normal user groups with their members. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md) | Gets all users and all user groups of the vault. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetUsersAndUserContainersOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainersOrDelta/index.md) | Gets users and user groups of all types as JSON, or only the changes since a version the caller already has. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetUsersAndUserGroupsList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsList/index.md) | Gets the names of all users and user groups in one list, with group IDs negated. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetUsersAndUserGroupsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/index.md) | Gets users and normal user groups as JSON, or only the changes since a version the caller already has. | `write` `session or assertion` `returns metadata structure version` |
| [GetVaultServerAttachments](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVaultServerAttachments/index.md) | Gets the servers this vault is attached to. | `read` `session` `idempotent` `returns metadata structure version` |
| [NotifyDataPushEvent](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/NotifyDataPushEvent/index.md) | Notify for server data push message change. In multi-server mode this is broadcast to all nodes and node that has client channel open can continue operation. | `write` `session` |
| [SendPushDataPendingHeartbeat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataPendingHeartbeat/index.md) | Sends a heartbeat signal as an early response for server data push (with non-zero request id). | `write` `session` `returns metadata structure version` |
| [SendPushDataResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md) | Sends a response for server data push. This is a response for request received with RequestPushDataAsync call (with non-zero request id). This call completes the push data cycle. | `write` `session` `returns metadata structure version` |
---
# IRPCVault.GetVault
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVault/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the GUID, display name and other basic data of the session's vault.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault`
- **Request:** [`GetVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVault/index.md#request)
- **Response:** [`GetVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVault/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Requires a vault session. `tooltip`, `icon` and `dns_names` are often empty. The response
carries the metadata structure version in the `mfiles-metadata-version-bin` trailer.
## Request: GetVaultRequest
A structure that specifies get vault request.
No fields.
## Response: GetVaultResponse
A structure that specifies get vault 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 |
|---|---|---|
| `vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | The vault the session is logged in to. |
| `vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault.display_name` | `string` | The vault name shown to users. |
| `vault.tooltip` | `string` | Optional description. Often empty. |
| `vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `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.dns_names.value[]` | repeated `string` | String values. |
## Related methods
- [GetVaultServerAttachments](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVaultServerAttachments/index.md): Gets the servers this vault is attached to.
---
# IRPCVault.GetMetadataStructureItemIdByAlias
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Finds the vault-specific ID of a metadata structure item from one of its aliases.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure-item-id-by-alias`
- **Request:** [`GetMetadataStructureItemIdByAliasRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/index.md#request)
- **Response:** [`GetMetadataStructureItemIdByAliasResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Aliases are names that the vault administrator gives to structure items so that code can refer
to them, for example `PD.InvoiceNumber`. One item can have several aliases.
Matching ignores case and leading and trailing spaces. When no item, or more than one item, of
the given type has the alias, `id` is -1; for `METADATA_STRUCTURE_ITEM_NAMED_ACL` it is -1000,
because -1 is a valid named ACL ID.
Supported `item_type` values: `OBJECT_TYPE`, `VALUE_LIST`, `PROPERTY_DEF`, `OBJECT_CLASS`,
`WORKFLOW`, `STATE`, `STATE_TRANSITION`, `NAMED_ACL` and `USER_GROUP` (all prefixed
`METADATA_STRUCTURE_ITEM_`). Object types and value lists are one collection: `OBJECT_TYPE` and
`VALUE_LIST` both search both. Other types and an empty alias fail with `E_INVALIDARG`.
To resolve many aliases, fetch them all at once with
[GetAllMetadataStructureItemIdswithAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md)
and cache the result with the metadata structure version.
## Request: GetMetadataStructureItemIdByAliasRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `item_type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The kind of item to look for. The method description lists the supported values. |
| `alias` | `string` | One alias, without the `;` that separates an item's aliases. Case does not matter. |
## Response: GetMetadataStructureItemIdByAliasResponse
> Nested 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 item's ID, or -1 (-1000 for named ACLs) if no item or several items of `item_type` have the alias. |
## Related methods
- [GetAllMetadataStructureItemIdswithAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md): Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as typed lists.
- [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md): Gets the vault's real object types (not value lists), with icons, in one call.
---
# IRPCVault.GetMetadataStructureItemIdsByAliases
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all
kinds, as JSON.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure-item-ids-by-aliases`
- **Request:** [`GetMetadataStructureItemIdsByAliasesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md#request)
- **Response:** [`GetMetadataStructureItemIdsByAliasesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`unambiguous_aliases_only` must be true; false fails with `E_NOTIMPL`. Aliases used by more than
one item of the same kind are left out.
`data` is UTF-8 JSON followed by one NUL byte. If `uncompressed_length` is 4294967295 the bytes
are the JSON as is; otherwise they are zlib-compressed (`zlib.decompress` in Python) and
`uncompressed_length` is the decompressed size including the NUL. The JSON maps the item kind to
an object of alias-to-ID pairs; kinds without aliases are left out, so an empty vault gives `{}`:
```json
{"PropertyDef": {"PD.InvoiceNumber": 1021}, "Class": {"CL.Invoice": 5}}
```
Kind names: `ObjectType`, `ValueList`, `PropertyDef`, `Class`, `Workflow`, `State`,
`StateTransition`, `NamedACL`, `UserGroup`. Aliases keep the case the administrator gave them.
Object types and value lists are one collection, so with `METADATA_STRUCTURE_ITEM_ALL` an alias of
either appears under both `ObjectType` and `ValueList`.
[GetAllMetadataStructureItemIdswithAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md)
returns the same data as typed messages and is easier to use.
## Request: GetMetadataStructureItemIdsByAliasesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `emsi` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The kind of item, or `METADATA_STRUCTURE_ITEM_ALL` for every kind that can have aliases. |
| `unambiguous_aliases_only` | `bool` | Must be true; false fails with `E_NOTIMPL`. |
## Response: GetMetadataStructureItemIdsByAliasesResponse
> Nested 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` | NUL-terminated UTF-8 JSON, zlib-compressed unless `uncompressed_length` is 4294967295. The method description shows the format. |
| `uncompressed_length` | `uint32` | Size of the decompressed `data`, or 4294967295 if `data` is not compressed. |
## Related methods
- [GetAllMetadataStructureItemIdswithAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md): Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as typed lists.
- [GetMetadataStructureItemIdsByAliases_Compressed](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed/index.md): Gets alias-to-ID mappings of several kinds of metadata structure item as JSON, with the option to exclude kinds.
- [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md): Gets the vault's real object types (not value lists), with icons, in one call.
---
# IRPCVault.GetMetadataStructureItemIdByGUID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Finds the vault-specific ID of a metadata structure item (object type, property definition,
class, workflow, ...) from its GUID.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure-item-id-by-guid`
- **Request:** [`GetMetadataStructureItemIdByGUIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md#request)
- **Response:** [`GetMetadataStructureItemIdByGUIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Use this to resolve structure items by GUID instead of hard-coding their vault-specific IDs.
Supported `item_type` values: `OBJECT_TYPE`, `VALUE_LIST`, `PROPERTY_DEF`, `OBJECT_CLASS`,
`CLASS_GROUP`, `WORKFLOW`, `STATE`, `STATE_TRANSITION`, `NAMED_ACL`, `USER`, `USER_GROUP` and
`VIEW_DEF` (all prefixed `METADATA_STRUCTURE_ITEM_`). Object types and value lists are one
collection: `OBJECT_TYPE` and `VALUE_LIST` both find either kind.
A GUID that matches nothing of the given type returns `is_found` false and `id` 0. An all-zero or
malformed GUID, and `METADATA_STRUCTURE_ITEM_VALUE_LIST_ITEM`, fail with `E_INVALIDARG`.
The result is cacheable; the response carries the metadata structure version in the
`mfiles-metadata-version-bin` trailer.
## Request: GetMetadataStructureItemIdByGUIDRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `item_type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The kind of item to look for. The method description lists the supported values. |
| `guid` | `string` | The item's GUID, with or without braces, in any case, for example `{9725854F-4A75-403F-A364-F390A67A0535}`. |
## Response: GetMetadataStructureItemIdByGUIDResponse
> Nested 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_found` | `bool` | True if an item of `item_type` has this GUID. |
| `id` | `int32` | The item's ID in this vault. 0 when `is_found` is false. |
## Related methods
- [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md): Gets the vault's real object types (not value lists), with icons, in one call.
---
# IRPCVault.GetUsersAndUserGroups
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all users and normal user groups of the vault as JSON.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUsersAndUserGroups`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users-and-user-groups`
- **Request:** [`GetUsersAndUserGroupsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md#request)
- **Response:** [`GetUsersAndUserGroupsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Prefer [GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md), which
returns the same kind of data as typed messages.
`users` and `groups` are UTF-8 JSON arrays followed by one NUL byte, each zlib-compressed unless
its length field is 4294967295. Users are `{"key": , "name": ""}`; groups
are `{"id": ..., "name": ..., "members": [], "type": "normal"}`. Only
normal user groups are included.
## Request: GetUsersAndUserGroupsRequest
No fields.
## Response: GetUsersAndUserGroupsResponse
> Nested 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` | `bytes` | NUL-terminated JSON array of users (`key`, `name`), zlib-compressed unless `uncompressed_users_length` is 4294967295. |
| `uncompressed_users_length` | `uint32` | Size of the decompressed `users`, or 4294967295 if `users` is not compressed. |
| `groups` | `bytes` | NUL-terminated JSON array of user groups (`id`, `name`, `members`, `type`), zlib-compressed unless `uncompressed_groups_length` is 4294967295. |
| `uncompressed_groups_length` | `uint32` | Size of the decompressed `groups`, or 4294967295 if `groups` is not compressed. |
## Related methods
- [GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md): Gets all users and all user groups of the vault.
- [GetUsersAndUserGroupsList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsList/index.md): Gets the names of all users and user groups in one list, with group IDs negated.
- [GetUsersAndUserGroupsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/index.md): Gets users and normal user groups as JSON, or only the changes since a version the caller already has.
---
# IRPCVault.GetMetadataStructureVersion
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the version numbers of the vault's metadata structure and of its property definitions.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructureVersion`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure-version`
- **Request:** [`GetMetadataStructureVersionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md#request)
- **Response:** [`GetMetadataStructureVersionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
A cheap check for structure changes. `metadata_structure_version` is the same number that other
methods return in the `mfiles-metadata-version-bin` trailer. This method itself sends no
trailer.
## Request: GetMetadataStructureVersionRequest
No fields.
## Response: GetMetadataStructureVersionResponse
A structure that specifies the response type for the GetMetadataStructureVersion 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 |
|---|---|---|
| `metadata_structure_version` | `int32` | The vault's metadata structure version. When it differs from the value your cache was built with, refresh cached structure data. |
| `property_defs_version` | `int32` | The version of the vault's property definitions. |
## Related methods
- [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md): Gets the vault's real object types (not value lists), with icons, in one call.
---
# IRPCVault.BroadcastRequest
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/BroadcastRequest/
Badges: `Vault API / core` `write` `session` `idempotent` `returns metadata structure version`
Broadcasts a vault level request.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/BroadcastRequest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/broadcast-request`
- **Request:** [`BroadcastRequestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/BroadcastRequest/index.md#request)
- **Response:** [`BroadcastRequestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/BroadcastRequest/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files administration tools. Requires full control of the vault. The only request type,
`BROADCAST_REQUEST_TYPE_RESTART_VAULT`, restarts the vault on all servers and waits for the restart
on this server. Other values fail with `E_INVALIDARG`.
## Request: BroadcastRequestRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `request_type` | [`BroadcastRequestType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.BroadcastRequestType/index.md) | The broadcast request type. Values: `BROADCAST_REQUEST_TYPE_RESTART_VAULT` (0). |
| `request_data` | `string` | The optional custom data that can be attached to the request. |
## Response: BroadcastRequestResponse
No fields.
---
# IRPCVault.GetAllMetadataStructureItemIdswithAliases
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all
kinds, as typed lists.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-all-metadata-structure-item-idswith-aliases`
- **Request:** [`GetAllMetadataStructureItemIdswithAliasesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md#request)
- **Response:** [`GetAllMetadataStructureItemIdswithAliasesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllMetadataStructureItemIdswithAliases/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The typed form of
[GetMetadataStructureItemIdsByAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md):
one list per kind in `metadata_structure_aliases`, each entry an alias and its ID. Lists of kinds
without aliases are empty. `unambiguous_aliases_only` must be true; false fails with
`E_NOTIMPL`. Fetch once and cache with the metadata structure version.
## Request: GetAllMetadataStructureItemIdswithAliasesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `emsi` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The kind of item, or `METADATA_STRUCTURE_ITEM_ALL` for every kind that can have aliases. |
| `unambiguous_aliases_only` | `bool` | Must be true. Aliases used by more than one item of the same kind are left out. |
## Response: GetAllMetadataStructureItemIdswithAliasesResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `metadata_structure_aliases` | [`MetadataStructureAliases`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureAliases/index.md) | Receives the output object. |
| `metadata_structure_aliases.class_metadatas[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the class. |
| `metadata_structure_aliases.class_metadatas[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.class_metadatas[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.class_metadatas[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.object_types[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the objecttype. |
| `metadata_structure_aliases.object_types[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.object_types[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.object_types[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.property_defs[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the propertydef. |
| `metadata_structure_aliases.property_defs[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.property_defs[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.property_defs[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.workflows[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the workflow. |
| `metadata_structure_aliases.workflows[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.workflows[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.workflows[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.states[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the state. |
| `metadata_structure_aliases.states[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.states[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.states[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.state_transitions[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the StateTransition. |
| `metadata_structure_aliases.state_transitions[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.state_transitions[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.state_transitions[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.named_acls[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the NamedACL. |
| `metadata_structure_aliases.named_acls[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.named_acls[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.named_acls[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.user_groups[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the usergroup. |
| `metadata_structure_aliases.user_groups[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.user_groups[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.user_groups[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
| `metadata_structure_aliases.value_lists[]` | repeated [`StructureAlias`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureAlias/index.md) | StructureAlias array related to the ValueList. |
| `metadata_structure_aliases.value_lists[].alias_name` | `string` | The metadata structure item alias name. |
| `metadata_structure_aliases.value_lists[].id` | `int32` | The metadata structure item ID. |
| `metadata_structure_aliases.value_lists[].allocated_as_new` | `bool` | True if the ID was allocated as new. |
## Related methods
- [GetMetadataStructureItemIdsByAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md): Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as JSON.
---
# IRPCVault.GetAllTranslations
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllTranslations/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets all translations of the vault's metadata structure names as one JSON document.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetAllTranslations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-all-translations`
- **Request:** [`GetAllTranslationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllTranslations/index.md#request)
- **Response:** [`GetAllTranslationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetAllTranslations/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Requires the rights to change the metadata structure and to see all objects; other users get an
access-denied error. Used by M-Files administration tools. The JSON nests objects by the four
parts of each translation ID and maps
language IDs to the translated strings.
## Request: GetAllTranslationsRequest
No fields.
## Response: GetAllTranslationsResponse
> Nested 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_json` | `string` | Receives the output object. |
---
# IRPCVault.GetGroupsOfUserOrGroup
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetGroupsOfUserOrGroup/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the user groups that a user or a user group belongs to.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetGroupsOfUserOrGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-groups-of-user-or-group`
- **Request:** [`GetGroupsOfUserOrGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetGroupsOfUserOrGroup/index.md#request)
- **Response:** [`GetGroupsOfUserOrGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetGroupsOfUserOrGroup/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetGroupsOfUserOrGroupRequest
> Nested 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_or_group_id` | `int32` | The ID of the user, or of the user group when `is_group` is true. |
| `is_group` | `bool` | True if `user_or_group_id` is a user group ID; false (default) for a user ID. |
## Response: GetGroupsOfUserOrGroupResponse
> Nested 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 [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | User groups (represented by UserGroupBasic structs). |
| `groups[].id` | `int32` | The ID of the user group. |
| `groups[].name` | `string` | The name of the group. |
| `groups[].members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `groups[].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). |
---
# IRPCVault.GetMetadataStructure
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the vault's real object types (not value lists), with icons, in one call.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructure`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure`
- **Request:** [`GetMetadataStructureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md#request)
- **Response:** [`GetMetadataStructureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Set `object_type_and_value_list_request.include_real_object_types` to true; with false, or with
no request part set, the lists come back empty. Value lists are not returned by this method; use
the object types and value lists services for those. The administrative request part requires the
right to see the full metadata structure and fails with `E_MFILES_ACCESS_DENIED` otherwise.
## Request: GetMetadataStructureRequest
A structure that specifies the request type for the GetMetadataStructure 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 |
|---|---|---|
| `object_type_and_value_list_request` | [`ObjectTypeAndValueListStructureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeAndValueListStructureRequest/index.md) | Requests the specified object types and value lists from the server when set. |
| `object_type_and_value_list_request.include_real_object_types` | `bool` | Requests real object types from the vault. |
| `object_type_and_value_list_admin_request` | [`ObjectTypeAndValueListAdminStructureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeAndValueListAdminStructureRequest/index.md) | Requests the specified administrative object types and value lists from the server when set. |
| `object_type_and_value_list_admin_request.include_real_object_types` | `bool` | Requests real administrative object types from the vault. |
## Response: GetMetadataStructureResponse
A structure that specifies the response type for the GetzMetadataStructure 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 |
|---|---|---|
| `object_type_and_value_list_response` | [`ObjectTypeAndValueListStructureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeAndValueListStructureResponse/index.md) | Receives the object types and value lists if they were requested. |
| `object_type_and_value_list_response.object_types_and_value_lists[]` | repeated [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | The object type and value list entries. |
| `object_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `object_type_and_value_list_response.object_types_and_value_lists[].name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `object_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `object_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `object_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `object_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].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_type_and_value_list_response.object_types_and_value_lists[].view_id` | `int32` | The ID of the object type specific view. |
| `object_type_and_value_list_admin_response` | [`ObjectTypeAndValueListAdminStructureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeAndValueListAdminStructureResponse/index.md) | Receives the administrative object types and value lists if they were requested. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[]` | repeated [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The object type and value list entries. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].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_type_and_value_list_admin_response.object_types_and_value_lists[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `object_type_and_value_list_admin_response.object_types_and_value_lists[].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_type_and_value_list_admin_response.object_types_and_value_lists[].version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |
## Related methods
- [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md): Finds the vault-specific ID of a metadata structure item (object type, property definition, class, workflow, ...) from its GUID.
- [GetMetadataStructureItemIdByAlias](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/index.md): Finds the vault-specific ID of a metadata structure item from one of its aliases.
- [GetMetadataStructureItemIdsByAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md): Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as JSON.
- [GetMetadataStructureItemIdsByAliases_Compressed](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed/index.md): Gets alias-to-ID mappings of several kinds of metadata structure item as JSON, with the option to exclude kinds.
- [GetMetadataStructureItemIdsFromMDCardConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsFromMDCardConfiguration/index.md): Gets metadata structure item IDs and related aliases or GUIDs which are used in Metadata card configuration value. Created for HttpServer.
- [GetMetadataStructureVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md): Gets the version numbers of the vault's metadata structure and of its property definitions.
---
# IRPCVault.GetMetadataStructureItemIdsByAliases_Compressed
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets alias-to-ID mappings of several kinds of metadata structure item as JSON, with the option to
exclude kinds.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure-item-ids-by-aliases_-compressed`
- **Request:** [`GetMetadataStructureItemIdsByAliases_CompressedRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed/index.md#request)
- **Response:** [`GetMetadataStructureItemIdsByAliases_CompressedResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases_Compressed/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Works like
[GetMetadataStructureItemIdsByAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md),
with the same JSON format and compression, but takes lists of kinds. `unambiguous_aliases_only`
must be true. Excluding `METADATA_STRUCTURE_ITEM_ALL` fails with `E_INVALIDARG`.
## Request: GetMetadataStructureItemIdsByAliases_CompressedRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `msi_array_included[]` | repeated [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The kinds of item to return. A single `METADATA_STRUCTURE_ITEM_ALL` means every kind that can have aliases. |
| `msi_array_excluded` | [`MetadataStructureItemArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureItemArray/index.md) | Optional. Kinds to leave out, typically together with `METADATA_STRUCTURE_ITEM_ALL` in `msi_array_included`. |
| `msi_array_excluded.value[]` | repeated [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | An array of the MetadataStructureItem values. |
| `unambiguous_aliases_only` | `bool` | Must be true; false fails with `E_NOTIMPL`. |
## Response: GetMetadataStructureItemIdsByAliases_CompressedResponse
> Nested 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` | NUL-terminated UTF-8 JSON, zlib-compressed unless `uncompressed_length` is 4294967295. |
| `uncompressed_length` | `uint32` | Size of the decompressed `data`, or 4294967295 if `data` is not compressed. |
## Related methods
- [GetMetadataStructureItemIdsByAliases](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsByAliases/index.md): Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as JSON.
- [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md): Gets the vault's real object types (not value lists), with icons, in one call.
---
# IRPCVault.GetMetadataStructureItemIdsFromMDCardConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsFromMDCardConfiguration/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets metadata structure item IDs and related aliases or GUIDs which are used in Metadata card configuration value. Created for HttpServer.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetMetadataStructureItemIdsFromMDCardConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-metadata-structure-item-ids-from-mdcard-configuration`
- **Request:** [`GetMetadataStructureItemIdsFromMDCardConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsFromMDCardConfiguration/index.md#request)
- **Response:** [`GetMetadataStructureItemIdsFromMDCardConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdsFromMDCardConfiguration/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to resolve the aliases and GUIDs that the vault's metadata card
configuration refers to. Returns UTF-8 JSON that maps item kinds to alias-or-GUID-to-ID pairs
(`{}` when there are none). Applications rarely need it.
## Request: GetMetadataStructureItemIdsFromMDCardConfigurationRequest
No fields.
## Response: GetMetadataStructureItemIdsFromMDCardConfigurationResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `item_ids` | `bytes` | Receives the output object. |
## Related methods
- [GetMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructure/index.md): Gets the vault's real object types (not value lists), with icons, in one call.
---
# IRPCVault.GetReportAccessCredentials
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetReportAccessCredentials/
Badges: `Vault API / core` `read` `session` `idempotent` `returns metadata structure version`
Gets the report access credentials for this vault. The credentials are encrypted with the provided public key.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetReportAccessCredentials`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-report-access-credentials`
- **Request:** [`GetReportAccessCredentialsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetReportAccessCredentials/index.md#request)
- **Response:** [`GetReportAccessCredentialsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetReportAccessCredentials/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files reporting components. Requires a server license that includes reporting;
otherwise fails with `E_MFILES_NO_LICENSE_FOR_REPORTING`. The credentials are encrypted with the
caller's public key.
## Request: GetReportAccessCredentialsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `public_key` | `bytes` | The public key as a BLOB for encrypting the credentials. |
## Response: GetReportAccessCredentialsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pimpersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Receives the report access credentials (represented by Impersonation sturct). |
| `pimpersonation.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). |
| `pimpersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `pimpersonation.encrypted_password` | `bytes` | Encrypted password. |
---
# IRPCVault.GetServerRoles
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetServerRoles/
Badges: `Vault API / core` `read` `session` `idempotent`
Gets the multi-server roles this server has with the vault.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetServerRoles`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-roles`
- **Request:** [`GetServerRolesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetServerRoles/index.md#request)
- **Response:** [`GetServerRolesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetServerRoles/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files in multi-server deployments to see which background roles this server runs for
the vault; applications rarely need it.
## Request: GetServerRolesRequest
No fields.
## Response: GetServerRolesResponse
> Nested 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_roles` | [`MultiServerRoles`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MultiServerRoles/index.md) | Receives the server roles struct. |
| `server_roles.role_vdelta` | `bool` | This server takes care of VDelta generation. |
| `server_roles.role_external_sync` | `bool` | Server takes care of external object type synchronization. |
| `server_roles.role_state_change` | `bool` | Server takes care of automatic state changes. |
| `server_roles.role_ext_file_mon` | `bool` | Server takes care of exteral file and mail synchronization operations. |
| `server_roles.role_notification_generation` | `bool` | Server takes care of sending notifications. |
| `server_roles.role_scheduled_jobs` | `bool` | Server takes care of running scheduled jobs. |
| `server_roles.role_user_group_sync` | `bool` | Server takes care of user group synchronization. |
| `server_roles.role_nightly_maintenance` | `bool` | Server takes care of nightly maintenance operations. |
| `server_roles.role_async_tasks` | `bool` | Server takes care of processing background tasks. |
| `server_roles.role_optimize_and_indexing` | `bool` | Server takes care of optimization and indexing operations. |
| `server_roles.role_data_export` | `bool` | Server takes care of data export. |
| `server_roles.role_analytics_processing` | `bool` | Server takes care of MFAnalytics processing for the vault. |
| `server_roles.role_remove_conflict_object` | `bool` | Server takes care of removing conflict object operation. |
| `server_roles.role_cleanup` | `bool` | True, if server takes care of cleanup operations. |
| `server_roles.role_master_storage_version_monitor` | `bool` | True, if server does automatic versioning for Master Storage live changes. |
| `server_roles.role_master_storage_sync` | `bool` | True, if server runs the master storage synchronization operations. |
| `server_roles.role_ipaas_notification` | `bool` | True, if server runs the Integration Platform as a Service notification processing operations. |
---
# IRPCVault.GetUserContainers
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserContainers/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets all user groups of the vault, of all group types, with their members.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUserContainers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-containers`
- **Request:** [`GetUserContainersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserContainers/index.md#request)
- **Response:** [`GetUserContainersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserContainers/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetUserContainersRequest
No fields.
## Response: GetUserContainersResponse
> Nested 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 [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | User groups (represented by UserGroupBasic structs). |
| `groups[].id` | `int32` | The ID of the user group. |
| `groups[].name` | `string` | The name of the group. |
| `groups[].members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `groups[].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). |
---
# IRPCVault.GetUserGroup
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroup/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets one user group with its members.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-group`
- **Request:** [`GetUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroup/index.md#request)
- **Response:** [`GetUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroup/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetUserGroupRequest
> Nested 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 (positive). |
## Response: GetUserGroupResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `putf8szugb` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The user group, with its name, type and members. |
| `putf8szugb.id` | `int32` | The ID of the user group. |
| `putf8szugb.name` | `string` | The name of the group. |
| `putf8szugb.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `putf8szugb.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). |
---
# IRPCVault.GetUserGroups
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the vault's normal user groups with their members.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUserGroups`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-groups`
- **Request:** [`GetUserGroupsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md#request)
- **Response:** [`GetUserGroupsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
[GetUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserContainers/index.md) returns groups of all types.
## Request: GetUserGroupsRequest
No fields.
## Response: GetUserGroupsResponse
> Nested 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 [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | User groups (represented by UserGroupBasic structs). |
| `groups[].id` | `int32` | The ID of the user group. |
| `groups[].name` | `string` | The name of the group. |
| `groups[].members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `groups[].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). |
## Related methods
- [GetUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserContainers/index.md): Gets all user groups of the vault, of all group types, with their members.
---
# IRPCVault.GetUsersAndUserContainers
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all users and all user groups of the vault.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUsersAndUserContainers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users-and-user-containers`
- **Request:** [`GetUsersAndUserContainersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md#request)
- **Response:** [`GetUsersAndUserContainersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The typed way to list users and groups. `users` gives each user's ID (`key`) and full name;
`groups` gives each group with its members (user IDs and group IDs). Includes groups of all
types, unlike [GetUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md).
## Request: GetUsersAndUserContainersRequest
No fields.
## Response: GetUsersAndUserContainersResponse
> Nested 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 [`KeyNamePair`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.KeyNamePair/index.md) | The users: `key` is the user ID, `name` the full name. |
| `users[].key` | `int32` | The unique key of the item. |
| `users[].name` | `string` | The display name of the item. |
| `groups[]` | repeated [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The user groups with their members. |
| `groups[].id` | `int32` | The ID of the user group. |
| `groups[].name` | `string` | The name of the group. |
| `groups[].members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `groups[].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). |
## Related methods
- [GetUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md): Gets the vault's normal user groups with their members.
- [GetUsersAndUserContainersOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainersOrDelta/index.md): Gets users and user groups of all types as JSON, or only the changes since a version the caller already has.
---
# IRPCVault.GetUsersAndUserContainersOrDelta
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainersOrDelta/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets users and user groups of all types as JSON, or only the changes since a version the caller
already has.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUsersAndUserContainersOrDelta`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users-and-user-containers-or-delta`
- **Request:** [`GetUsersAndUserContainersOrDeltaRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainersOrDelta/index.md#request)
- **Response:** [`GetUsersAndUserContainersOrDeltaResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainersOrDelta/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Works like
[GetUsersAndUserGroupsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/index.md) but includes
groups of all types. Used by M-Files clients; applications usually call
[GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md) instead.
## Request: GetUsersAndUserContainersOrDeltaRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callers_current_users_version` | `int64` | The users version from your previous call, or 0 to get all users. |
| `callers_current_user_groups_version` | `int64` | The user groups version from your previous call, or 0 to get all groups. |
| `allow_receiving_delta` | `bool` | True to accept only the changes since the versions given. |
## Response: GetUsersAndUserContainersOrDeltaResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `current_users_version_on_server` | `int64` | Receives the current version of the Users value list's data on the server. If this is the same as the one specified by the caller, no users are returned. |
| `current_user_groups_version_on_server` | `int64` | Receives the current version of the User Groups value list's data on the server. If this is the same as the one specified by the caller, no user groups are returned. |
| `users` | `bytes` | NUL-terminated JSON object (`isDelta`, `removedUsers`, `users`), zlib-compressed unless `uncompressed_users_length` is 4294967295. |
| `uncompressed_users_length` | `uint32` | Size of the decompressed `users`, or 4294967295 if not compressed. |
| `groups` | `bytes` | NUL-terminated JSON object with the groups or their changes, zlib-compressed unless `uncompressed_groups_length` is 4294967295. |
| `uncompressed_groups_length` | `uint32` | Size of the decompressed `groups`, or 4294967295 if not compressed. |
## Related methods
- [GetUsersAndUserGroupsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/index.md): Gets users and normal user groups as JSON, or only the changes since a version the caller already has.
- [GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md): Gets all users and all user groups of the vault.
---
# IRPCVault.GetUsersAndUserGroupsList
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsList/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the names of all users and user groups in one list, with group IDs negated.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUsersAndUserGroupsList`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users-and-user-groups-list`
- **Request:** [`GetUsersAndUserGroupsListRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsList/index.md#request)
- **Response:** [`GetUsersAndUserGroupsListResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsList/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Convenient for a picker: users have positive `key` values (the user ID), groups negative values
(minus the group ID). For example group 102 appears as `-102`.
## Request: GetUsersAndUserGroupsListRequest
No fields.
## Response: GetUsersAndUserGroupsListResponse
> Nested 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_and_user_groups[]` | repeated [`KeyNamePair`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.KeyNamePair/index.md) | Users (positive `key` = user ID) followed by user groups (negative `key` = minus the group ID). |
| `users_and_user_groups[].key` | `int32` | The unique key of the item. |
| `users_and_user_groups[].name` | `string` | The display name of the item. |
## Related methods
- [GetUsersAndUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md): Gets all users and normal user groups of the vault as JSON.
---
# IRPCVault.GetUsersAndUserGroupsOrDelta
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets users and normal user groups as JSON, or only the changes since a version the caller
already has.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users-and-user-groups-or-delta`
- **Request:** [`GetUsersAndUserGroupsOrDeltaRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/index.md#request)
- **Response:** [`GetUsersAndUserGroupsOrDeltaResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroupsOrDelta/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to keep a local copy of the user lists; applications usually call
[GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md) instead.
Send 0 for both versions to get everything. Later, send the `current_..._version_on_server`
values you received with `allow_receiving_delta` true: if nothing changed, the JSON is an empty
delta (`{"isDelta":true,"removedUsers":[],"users":[]}` for users). `users` and `groups` are
NUL-terminated UTF-8 JSON objects, zlib-compressed unless their length field is 4294967295.
## Request: GetUsersAndUserGroupsOrDeltaRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callers_current_users_version` | `int64` | The users version from your previous call, or 0 to get all users. |
| `callers_current_user_groups_version` | `int64` | The user groups version from your previous call, or 0 to get all groups. |
| `allow_receiving_delta` | `bool` | True to accept only the changes since the versions given. |
## Response: GetUsersAndUserGroupsOrDeltaResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `current_users_version_on_server` | `int64` | The current users version. Send it in the next call. |
| `current_user_groups_version_on_server` | `int64` | The current user groups version. Send it in the next call. |
| `users` | `bytes` | NUL-terminated JSON object (`isDelta`, `removedUsers`, `users`), zlib-compressed unless `uncompressed_users_length` is 4294967295. |
| `uncompressed_users_length` | `uint32` | Size of the decompressed `users`, or 4294967295 if not compressed. |
| `groups` | `bytes` | NUL-terminated JSON object with the groups or their changes, zlib-compressed unless `uncompressed_groups_length` is 4294967295. |
| `uncompressed_groups_length` | `uint32` | Size of the decompressed `groups`, or 4294967295 if not compressed. |
## Related methods
- [GetUsersAndUserContainers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserContainers/index.md): Gets all users and all user groups of the vault.
- [GetUsersAndUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md): Gets all users and normal user groups of the vault as JSON.
---
# IRPCVault.GetVaultServerAttachments
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVaultServerAttachments/
Badges: `Vault API / core` `read` `session` `idempotent` `returns metadata structure version`
Gets the servers this vault is attached to.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/GetVaultServerAttachments`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-server-attachments`
- **Request:** [`GetVaultServerAttachmentsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVaultServerAttachments/index.md#request)
- **Response:** [`GetVaultServerAttachmentsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVaultServerAttachments/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files in multi-server deployments; applications rarely need it. Lists the servers the
vault is attached to; on a single server the list has one entry with `is_current` true.
## Request: GetVaultServerAttachmentsRequest
No fields.
## Response: GetVaultServerAttachmentsResponse
> Nested 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_server_attachments[]` | repeated [`VaultServerAttachment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultServerAttachment/index.md) | Receives the vault server attachments. |
| `vault_server_attachments[].host_name` | `string` | The server host name. |
| `vault_server_attachments[].address` | `string` | The server host address. |
| `vault_server_attachments[].server_id` | `string` | The server ID. |
| `vault_server_attachments[].latest_timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The latest timestamp this info was updated. |
| `vault_server_attachments[].is_current` | `bool` | True if this is the current vault server attachment. |
## Related methods
- [GetVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetVault/index.md): Gets the GUID, display name and other basic data of the session's vault.
---
# IRPCVault.NotifyDataPushEvent
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/NotifyDataPushEvent/
Badges: `Vault API / core` `write` `session`
Notify for server data push message change. In multi-server mode this is broadcast to all nodes and node that has client channel open can continue operation.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/NotifyDataPushEvent`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/notify-data-push-event`
- **Request:** [`NotifyDataPushEventRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/NotifyDataPushEvent/index.md#request)
- **Response:** [`NotifyDataPushEventResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/NotifyDataPushEvent/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Part of server data push, used by M-Files clients and servers in multi-server deployments to
pass a push event to the server that holds the client's push channel. Applications rarely need
it.
## Request: NotifyDataPushEventRequest
A structure that specifies notify data push event 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 |
|---|---|---|
| `request_id` | `int32` | The request id, should match with the request id that was received from of the RequestPushDataAsync call. |
| `notify_type` | [`ServerDataPushNotifyType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerDataPushNotifyType/index.md) | The notify type. 0 = unknown, 1 = request, 2 = response, 3 = hearbeat. Values: `SERVER_DATA_PUSH_NOTIFY_TYPE_UNKNOWN` (0), `SERVER_DATA_PUSH_NOTIFY_TYPE_REQUEST` (1), `SERVER_DATA_PUSH_NOTIFY_TYPE_RESPONSE` (2), `SERVER_DATA_PUSH_NOTIFY_TYPE_HEARTBEAT` (3). |
## Response: NotifyDataPushEventResponse
The response of NotifyDataPushEvent. Has no data.
No fields.
---
# IRPCVault.SendPushDataPendingHeartbeat
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataPendingHeartbeat/
Badges: `Vault API / core` `write` `session` `returns metadata structure version`
Sends a heartbeat signal as an early response for server data push (with non-zero request id). If the client cannot provide final response in 20 seconds, the client should be sending a heartbeat signal for server that prevents server from terminating the request.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/SendPushDataPendingHeartbeat`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/send-push-data-pending-heartbeat`
- **Request:** [`SendPushDataPendingHeartbeatRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataPendingHeartbeat/index.md#request)
- **Response:** [`SendPushDataPendingHeartbeatResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataPendingHeartbeat/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **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)
## Remarks
Part of server data push. A client that needs more time to answer a push request sends this
within 20 seconds, and again as needed, so that the server keeps waiting for
[SendPushDataResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md).
## Request: SendPushDataPendingHeartbeatRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `response_id` | `int32` | The response id, should match with the request id that was received from of the RequestPushDataAsync call. |
## Response: SendPushDataPendingHeartbeatResponse
No fields.
## Related methods
- [SendPushDataResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md): Sends a response for server data push. This is a response for request received with RequestPushDataAsync call (with non-zero request id). This call completes the push data cycle.
---
# IRPCVault.SendPushDataResponse
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/
Badges: `Vault API / core` `write` `session` `returns metadata structure version`
Sends a response for server data push. This is a response for request received with RequestPushDataAsync call (with non-zero request id). This call completes the push data cycle.
- **Service:** [Vault information](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md) `MFiles.IRPCVault`
- **gRPC method:** `/MFiles.IRPCVault/SendPushDataResponse`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/send-push-data-response`
- **Request:** [`SendPushDataResponseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md#request)
- **Response:** [`SendPushDataResponseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **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)
## Remarks
Part of server data push, used by M-Files clients that open a push channel with
[OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md). Sends the client's
answer to a push request that expects one; `response_id` is the ID of that request.
## Request: SendPushDataResponseRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `response_id` | `int32` | The response id, should match with the request id that was received from of the RequestPushDataAsync call. |
| `response_json` | `string` | The response data for previous callback. |
## Response: SendPushDataResponseResponse
No fields.
## Related methods
- [IRPCServerDataPush.OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md): Opens the session's push channel: a stream of requests and notifications from the server.
---
# Object types (IRPCObjectTypes)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/
An interface for reading object types.
This interface provides read-only access to object types.
- **gRPC service:** `MFiles.IRPCObjectTypes`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCObjectTypes.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCObjectTypes.proto)
## Overview
Reads the object types of the vault: the kinds of objects users create, such as Document (0),
Customer or Project. Use it to resolve object type IDs to names, find the property definition
that refers to objects of a type, and check whether the user can create objects of a type.
| Job | Call |
| --- | --- |
| List all object types (with icons) | [GetObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md) |
| Read one object type or value list by ID | [GetObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/index.md) |
| Object types *and* plain value lists, without icons | [GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md) |
| Ask the server to re-read an external object type now | [RefreshExternalObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/RefreshExternalObjectType/index.md) |
**ID spaces.** An object type is a value list whose items are objects, so object types and value
lists share one ID space and both are described by [ValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md)
(`is_real_object_type` tells them apart). Property definition IDs
([IRPCPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)) are a separate space, and so are the item
IDs inside each list: a class ID, for example, is an item ID in value list 1 (Classes). Built-in
object types keep their IDs in every vault (0 Document, 9 Document collection, 10 Assignment);
the IDs of custom object types differ between vaults, so resolve them by alias or GUID with
[GetMetadataStructureItemIdByAlias](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/index.md)
instead of hard-coding them.
The read calls are cacheable: keep the result until the metadata structure version that the server returns
in the `mfiles-metadata-version-bin` trailer changes. See
[Vault and metadata structure](https://developer.m-files.com/APIs/gRPC-API/concepts/vault-and-metadata-structure/index.md)
and
[Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/index.md) | Gets one object type or value list by ID, with its icon. | `write` `session or assertion` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [RefreshExternalObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/RefreshExternalObjectType/index.md) | Refreshes the items of an external object type or value list from its external database now. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
---
# IRPCObjectTypes.GetObjectTypes
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all object types (real object types only, not plain value lists), with their icons.
- **Service:** [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md) `MFiles.IRPCObjectTypes`
- **gRPC method:** `/MFiles.IRPCObjectTypes/GetObjectTypes`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-types`
- **Request:** [`GetObjectTypesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md#request)
- **Response:** [`GetObjectTypesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Returns only real object types (`is_real_object_type` is true). For plain value lists such as
Country, call [GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md), which returns both
kinds but no icons.
- Object types that the user is not allowed to see are **not** left out: they are returned with
empty `name_singular` and `name_plural`, and `object_type_permissions.can_user_see` false.
Filter on `object_type_permissions` before showing a list to the user.
- `object_type_permissions.can_user_add_new_items` tells whether the user may create objects
of the type; `options.can_add_items` tells whether the type allows new objects at all.
- Names are in the session language when the vault has translations for it.
- `icon` holds the type's .ICO image (about 17 KB for the default icon), so the response grows
with the number of types.
- Cacheable by metadata structure version.
## Request: GetObjectTypesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically CALL_IMPORTANCE_NORMAL. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
## Response: GetObjectTypesResponse
> 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 |
|---|---|---|
| `object_types[]` | repeated [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | The real object types of the vault, including those the user cannot see (with empty names). See [ValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md). |
| `object_types[].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[].name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `object_types[].name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `object_types[].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[].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[].is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `object_types[].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[].owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `object_types[].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[].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[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_types[].options.can_have_files` | `bool` | Can objects have files? |
| `object_types[].options.can_add_items` | `bool` | True if new items (value lists) or new objects (object types) can be added. The caller also needs `ValueList.object_type_permissions.can_user_add_new_items`. |
| `object_types[].options.is_external` | `bool` | True if the list is marked external. Built-in lists such as Users (6), Workflows (7) and User groups (16) also have this flag. |
| `object_types[].options.show_new_object_command_in_task_pane` | `bool` | Show the creation command for this type in the task pane? |
| `object_types[].options.is_external_connection_disabled` | `bool` | Is external connection currently disabled? |
| `object_types[].options.is_translatable` | `bool` | Can the contents of value list or object type be translated? |
| `object_types[].options.is_separate_property_storage` | `bool` | True if the object type has its own storage of property values for searches. |
| `object_types[].options.disallow_as_grouping_level` | `bool` | Is using this object type as a grouping level in views disallowed? |
| `object_types[].options.basic` | `bool` | Is basic tier object type? |
| `object_types[].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[].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[].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[].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[].targets_for_browsing[].target_object_type` | `int32` | The ID of the target object type. |
| `object_types[].targets_for_browsing[].view` | `int32` | The ID of the view collection where instances of the target object type are being browsed. This view collection resides in the predefined Built-in Views view folder. |
| `object_types[].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[].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. |
| `object_types[].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. |
| `object_types[].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. |
| `object_types[].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. |
| `object_types[].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. |
| `object_types[].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. |
| `object_types[].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_permissions.can_user_see` | `bool` | The object type is visible for the current user (provided for symmetry). |
| `object_types[].object_type_permissions.can_user_add_new_items` | `bool` | The current user can add new items. |
| `object_types[].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[].default_acl_for_objects.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. |
| `object_types[].default_acl_for_objects.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. |
| `object_types[].default_acl_for_objects.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `object_types[].default_acl_for_objects.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. |
| `object_types[].default_acl_for_objects.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. |
| `object_types[].default_acl_for_objects.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. |
| `object_types[].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[].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[].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[].preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `object_types[].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[].search_characteristics.exclude_in_entire_file_data_search` | `bool` | Specifies whether object type is excluded from file content searches. |
| `object_types[].search_characteristics.exclude_in_entire_meta_data_search` | `bool` | Specifies whether object type is excluded from metadata searches. |
| `object_types[].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[].indexing_definition.indexed_value_lists[]` | repeated `int32` | IDs of indexed value lists. |
| `object_types[].indexing_definition.indexed_properties[]` | repeated `int32` | IDs of indexed properties. |
| `object_types[].view_id` | `int32` | The ID of the object type specific view. |
## 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.
---
# IRPCObjectTypes.GetObjectType
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets one object type or value list by ID, with its icon.
- **Service:** [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md) `MFiles.IRPCObjectTypes`
- **gRPC method:** `/MFiles.IRPCObjectTypes/GetObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-type`
- **Request:** [`GetObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/index.md#request)
- **Response:** [`GetObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Accepts any ID from the shared object type / value list ID space: a real object type (for
example 136) or a plain value list (for example 154) both work. Only real object types carry
an icon.
- An ID that does not exist fails with the error message "Not found." (gRPC status `UNKNOWN`).
- An object type that the user cannot see is returned with empty names and
`object_type_permissions.can_user_see` false; it does not fail.
- Cacheable by metadata structure version.
- Related: [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md) returns the same data
without the icon.
## Request: GetObjectTypeRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callimp` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `object_type` | `int32` | The ID of the object type or value list to get. |
## Response: GetObjectTypeResponse
> 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 |
|---|---|---|
| `putf8szobjtypebasic` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | The object type or value list. See [ValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md). |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `putf8szobjtypebasic.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `putf8szobjtypebasic.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `putf8szobjtypebasic.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). |
| `putf8szobjtypebasic.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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). |
| `putf8szobjtypebasic.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `putf8szobjtypebasic.options.can_have_files` | `bool` | Can objects have files? |
| `putf8szobjtypebasic.options.can_add_items` | `bool` | True if new items (value lists) or new objects (object types) can be added. The caller also needs `ValueList.object_type_permissions.can_user_add_new_items`. |
| `putf8szobjtypebasic.options.is_external` | `bool` | True if the list is marked external. Built-in lists such as Users (6), Workflows (7) and User groups (16) also have this flag. |
| `putf8szobjtypebasic.options.show_new_object_command_in_task_pane` | `bool` | Show the creation command for this type in the task pane? |
| `putf8szobjtypebasic.options.is_external_connection_disabled` | `bool` | Is external connection currently disabled? |
| `putf8szobjtypebasic.options.is_translatable` | `bool` | Can the contents of value list or object type be translated? |
| `putf8szobjtypebasic.options.is_separate_property_storage` | `bool` | True if the object type has its own storage of property values for searches. |
| `putf8szobjtypebasic.options.disallow_as_grouping_level` | `bool` | Is using this object type as a grouping level in views disallowed? |
| `putf8szobjtypebasic.options.basic` | `bool` | Is basic tier object type? |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `putf8szobjtypebasic.targets_for_browsing[].target_object_type` | `int32` | The ID of the target object type. |
| `putf8szobjtypebasic.targets_for_browsing[].view` | `int32` | The ID of the view collection where instances of the target object type are being browsed. This view collection resides in the predefined Built-in Views view folder. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.object_type_permissions.can_user_see` | `bool` | The object type is visible for the current user (provided for symmetry). |
| `putf8szobjtypebasic.object_type_permissions.can_user_add_new_items` | `bool` | The current user can add new items. |
| `putf8szobjtypebasic.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). |
| `putf8szobjtypebasic.default_acl_for_objects.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. |
| `putf8szobjtypebasic.default_acl_for_objects.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. |
| `putf8szobjtypebasic.default_acl_for_objects.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `putf8szobjtypebasic.default_acl_for_objects.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. |
| `putf8szobjtypebasic.default_acl_for_objects.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. |
| `putf8szobjtypebasic.default_acl_for_objects.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. |
| `putf8szobjtypebasic.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). |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.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). |
| `putf8szobjtypebasic.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.search_characteristics.exclude_in_entire_file_data_search` | `bool` | Specifies whether object type is excluded from file content searches. |
| `putf8szobjtypebasic.search_characteristics.exclude_in_entire_meta_data_search` | `bool` | Specifies whether object type is excluded from metadata searches. |
| `putf8szobjtypebasic.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. |
| `putf8szobjtypebasic.indexing_definition.indexed_value_lists[]` | repeated `int32` | IDs of indexed value lists. |
| `putf8szobjtypebasic.indexing_definition.indexed_properties[]` | repeated `int32` | IDs of indexed properties. |
| `putf8szobjtypebasic.view_id` | `int32` | The ID of the object type specific view. |
## Related methods
- [IRPCValueLists.GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md): Gets one value list or object type by ID, without its icon.
---
# IRPCObjectTypes.RefreshExternalObjectType
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/RefreshExternalObjectType/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Refreshes the items of an external object type or value list from its external database now.
- **Service:** [Object types](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md) `MFiles.IRPCObjectTypes`
- **gRPC method:** `/MFiles.IRPCObjectTypes/RefreshExternalObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/refresh-external-object-type`
- **Request:** [`RefreshExternalObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/RefreshExternalObjectType/index.md#request)
- **Response:** [`RefreshExternalObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/RefreshExternalObjectType/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session and a license that allows modifications.
- For an object type that is not connected to an external database, the call succeeds and does
nothing.
- Fails if the external connection of the object type is disabled, or if the connection or its
SELECT statement does not work.
- Rarely needed by applications: the lookup calls of
[IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) take an `ExtDBRefreshType` that can refresh
an external list as part of the read.
## Request: RefreshExternalObjectTypeRequest
> Nested 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 to refresh. |
| `ext_dbrefresh_type` | [`ExtDBRefreshType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtDBRefreshType/index.md) | `EXT_DBREFRESH_TYPE_QUICK` or `EXT_DBREFRESH_TYPE_FULL`. Values: `EXT_DBREFRESH_TYPE_NONE` (0), `EXT_DBREFRESH_TYPE_QUICK` (1), `EXT_DBREFRESH_TYPE_FULL` (2). |
## Response: RefreshExternalObjectTypeResponse
No fields.
---
# Property definitions and classes (IRPCPropertyDefs)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/
An interface for retrieving property definitions.
Provides methods for read-only access to PropertyDefs.
- **gRPC service:** `MFiles.IRPCPropertyDefs`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCPropertyDefs.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCPropertyDefs.proto)
## Overview
Reads property definitions and classes: what metadata objects can have and how it is grouped.
| Job | Call |
| --- | --- |
| All property definitions (names, data types, lookup targets) | [GetPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md) |
| One property definition | [GetPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDef/index.md) |
| All classes and class groups | [GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md) |
| One class, for example to build a metadata card | [GetObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClass/index.md) |
**ID spaces.** Property definition IDs, class IDs, class group IDs and object type IDs are
separate number spaces; the same number means different things in each.
- A property definition ID identifies a property such as 0 (Name or title), 100 (Class) or
1079 (Customer). Built-in property definitions have the same ID in every vault.
- A class is an item of value list 1 (Classes); its ID is
`base_info.item_info.obj_id.item_id.internal_id` of [ObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClass/index.md).
Class 0 is Document; the default classes of some built-in object types have negative IDs
(for example -100 Assignment). A class belongs to exactly one object type
(`ObjectClass.object_type`).
- A class group is an item of value list 2 (Class groups).
- A lookup property points to an object type or value list with `PropertyDef.value_list`.
IDs of custom property definitions and classes differ between vaults: resolve them by alias or
GUID with [GetMetadataStructureItemIdByAlias](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByAlias/index.md).
How property values are written and read is described in
[Properties and values](https://developer.m-files.com/APIs/gRPC-API/concepts/properties-and-values/index.md).
All four calls are cacheable by the metadata structure version (`mfiles-metadata-version-bin` trailer).
[GetPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md) and
[GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md) also take
a `known_version`, so a client that keeps a cache can ask for the data only when it has changed.
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDef/index.md) | Gets one property definition by ID. | `write` `session or assertion` `returns metadata structure version` |
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClass/index.md) | Gets one class by ID, with the property definitions associated with it. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
---
# IRPCPropertyDefs.GetPropertyDefs
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all property definitions that the user is allowed to see.
- **Service:** [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md) `MFiles.IRPCPropertyDefs`
- **gRPC method:** `/MFiles.IRPCPropertyDefs/GetPropertyDefs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-property-defs`
- **Request:** [`GetPropertyDefsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md#request)
- **Response:** [`GetPropertyDefsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Property definitions that the user cannot see (because of the property definition's
permissions) are left out. The owner property definitions of built-in object types that can
never have an owner are also left out.
- Names are in the session language when the vault has translations for it.
- **Change check:** send the `current_version` of the previous response as `known_version`. If
nothing has changed, the response has the same `current_version` and an **empty**
`property_defs`: keep your cached list, do not treat it as "no property definitions". Send 0
to always get the full list. This version counter is separate from the class version of
[GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md).
- Whether a property is required depends on the class, not on the property definition: read
`associated_property_defs` of [ObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClass/index.md).
- Cacheable by metadata structure version.
## Request: GetPropertyDefsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `include_icons` | `bool` | Ignored by the server; the response is the same for true and false. |
| `known_version` | `int32` | The `current_version` from the caller's previous response, or 0 to get all property definitions. If it equals the server's current version, `property_defs` is empty. |
## Response: GetPropertyDefsResponse
> 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 |
|---|---|---|
| `current_version` | `int32` | The current version of the property definitions on the server. Store it and send it as `known_version` next time. |
| `property_defs[]` | repeated [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | The property definitions the user can see, or empty if `known_version` was current. See [PropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md). |
| `property_defs[].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. |
| `property_defs[].name` | `string` | The name of the property. |
| `property_defs[].tooltip` | `string` | The tip text of this property. |
| `property_defs[].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). |
| `property_defs[].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). |
| `property_defs[].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). |
| `property_defs[].enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `property_defs[].is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `property_defs[].disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].value_list_item_filter[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `property_defs[].value_list_item_filter[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `property_defs[].value_list_item_filter[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `property_defs[].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). |
| `property_defs[].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). |
| `property_defs[].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. |
| `property_defs[].default_value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property_defs[].default_value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property_defs[].default_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. |
| `property_defs[].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). |
| `property_defs[].icon.value` | `bytes` | Array of bytes. |
| `property_defs[].is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `property_defs[].allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `property_defs[].is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `property_defs[].is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `property_defs[].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. |
| `property_defs[].owner_property_def_info.property_def` | `int32` | The ID of the owner property definition, or -106 if the owner property is determined automatically. |
| `property_defs[].owner_property_def_info.dependency_relation` | [`DependencyRelation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DependencyRelation/index.md) | How this property depends on its owner property: `DEPENDENCY_RELATION_FILTER` limits its values to those that belong to the owner property's value, `DEPENDENCY_RELATION_FILL` fills it automatically from the owner property's value. Values: `DEPENDENCY_RELATION_NOTHING` (0), `DEPENDENCY_RELATION_FILL` (1), `DEPENDENCY_RELATION_FILTER` (2). |
| `property_defs[].owner_property_def_info.data` | [`DependentPropertyDefUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DependentPropertyDefUnion/index.md) | Details of the `DEPENDENCY_RELATION_FILL` relation. |
| `property_defs[].object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].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. |
| `property_defs[].property_def_permissions.current_user_can_see` | `bool` | The property def is visible for the current user (provided for symmetry). |
| `property_defs[].property_def_permissions.current_user_can_edit` | `bool` | The current user can edit the values. |
| `property_defs[].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). |
| `property_defs[].value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `property_defs[].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). |
| `property_defs[].validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `property_defs[].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). |
| `property_defs[].formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `property_defs[].guid` | `string` | The GUID of the property definition, with braces. |
| `property_defs[].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). |
| `property_defs[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `property_defs[].options.can_use_in_search` | `bool` | Are objects searchable by this property? |
| `property_defs[].options.can_use_in_history_search` | `bool` | Are history versions of objects searchable by this property? |
| `property_defs[].options.show_only_filtered_values` | `bool` | Should only the values matching the property filter be shown on the metadata card? |
| `is_property_def_required[]` | repeated `bool` | Always empty. Required properties are defined per class: see `ObjectClass.associated_property_defs`. |
## Related methods
- [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.
---
# IRPCPropertyDefs.GetPropertyDef
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDef/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets one property definition by ID.
- **Service:** [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md) `MFiles.IRPCPropertyDefs`
- **gRPC method:** `/MFiles.IRPCPropertyDefs/GetPropertyDef`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-property-def`
- **Request:** [`GetPropertyDefRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDef/index.md#request)
- **Response:** [`GetPropertyDefResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDef/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Fails with the error message "You can't get access to the property ..." both when the ID
does not exist and when the user is not allowed to see the property definition. IDs 1-19
are never real property definitions (see
[SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md)
for their use in value list item searches).
- `property_def_permissions` is set only when the property definition has its own permissions.
- Cacheable by metadata structure version.
## Request: GetPropertyDefRequest
> Nested 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. |
| `icons` | `bool` | Ignored by the server. |
## Response: GetPropertyDefResponse
> 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 |
|---|---|---|
| `value` | [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | The property definition. See [PropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md). |
| `value.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. |
| `value.name` | `string` | The name of the property. |
| `value.tooltip` | `string` | The tip text of this property. |
| `value.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). |
| `value.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). |
| `value.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). |
| `value.enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `value.is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `value.disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `value.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. |
| `value.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. |
| `value.value_list_item_filter[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `value.value_list_item_filter[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `value.value_list_item_filter[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `value.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). |
| `value.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). |
| `value.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. |
| `value.default_value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `value.default_value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `value.default_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. |
| `value.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). |
| `value.icon.value` | `bytes` | Array of bytes. |
| `value.is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `value.allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `value.is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `value.is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `value.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. |
| `value.owner_property_def_info.property_def` | `int32` | The ID of the owner property definition, or -106 if the owner property is determined automatically. |
| `value.owner_property_def_info.dependency_relation` | [`DependencyRelation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DependencyRelation/index.md) | How this property depends on its owner property: `DEPENDENCY_RELATION_FILTER` limits its values to those that belong to the owner property's value, `DEPENDENCY_RELATION_FILL` fills it automatically from the owner property's value. Values: `DEPENDENCY_RELATION_NOTHING` (0), `DEPENDENCY_RELATION_FILL` (1), `DEPENDENCY_RELATION_FILTER` (2). |
| `value.owner_property_def_info.data` | [`DependentPropertyDefUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DependentPropertyDefUnion/index.md) | Details of the `DEPENDENCY_RELATION_FILL` relation. |
| `value.object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `value.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. |
| `value.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. |
| `value.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. |
| `value.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. |
| `value.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. |
| `value.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. |
| `value.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. |
| `value.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. |
| `value.property_def_permissions.current_user_can_see` | `bool` | The property def is visible for the current user (provided for symmetry). |
| `value.property_def_permissions.current_user_can_edit` | `bool` | The current user can edit the values. |
| `value.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). |
| `value.value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `value.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). |
| `value.validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `value.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). |
| `value.formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `value.guid` | `string` | The GUID of the property definition, with braces. |
| `value.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). |
| `value.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `value.options.can_use_in_search` | `bool` | Are objects searchable by this property? |
| `value.options.can_use_in_history_search` | `bool` | Are history versions of objects searchable by this property? |
| `value.options.show_only_filtered_values` | `bool` | Should only the values matching the property filter be shown on the metadata card? |
## 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.
---
# IRPCPropertyDefs.GetObjectClassesAndGroups
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all classes and class groups that the user is allowed to see.
- **Service:** [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md) `MFiles.IRPCPropertyDefs`
- **gRPC method:** `/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-classes-and-groups`
- **Request:** [`GetObjectClassesAndGroupsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md#request)
- **Response:** [`GetObjectClassesAndGroupsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Returns the classes of all object types; group or filter them by `object_type`.
- Deleted classes are left out, and so are classes and class groups the user is not allowed to
see. In each class, `associated_property_defs` lists only the property definitions the user
can see.
- `current_user_permissions.can_user_attach_objects` tells whether the user may attach objects
to the class; offer only such classes when the user creates an object.
- **Change check:** send the `current_version` of the previous response as `known_version`. If
nothing has changed, the response has the same `current_version` and **empty** `classes` and
`class_groups`. Send 0 to always get everything.
- Names are in the session language when the vault has translations for it.
- Cacheable by metadata structure version.
## Request: GetObjectClassesAndGroupsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `known_version` | `int64` | The `current_version` from the caller's previous response, or 0 to get all classes and class groups. If it is still current, both result lists are empty. |
## Response: GetObjectClassesAndGroupsResponse
> 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 |
|---|---|---|
| `current_version` | `int64` | The current version of the classes on the server. Store it and send it as `known_version` next time. |
| `classes[]` | repeated [`ObjectClass`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClass/index.md) | The classes the user can see, or empty if `known_version` was current. See [ObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClass/index.md). |
| `classes[].base_info` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The class as an item of value list 1 (Classes). The class ID is `base_info.item_info.obj_id.item_id.internal_id` and its name `base_info.item_info.name`. |
| `classes[].base_info.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. |
| `classes[].base_info.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `classes[].base_info.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `classes[].base_info.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `classes[].base_info.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `classes[].base_info.owner_name` | `string` | The name of the owner item. |
| `classes[].base_info.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. |
| `classes[].base_info.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. |
| `classes[].associated_property_defs[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | The properties of objects of this class, each with `is_required`. Lists only property definitions the caller can see, and includes the built-in properties that every object has (such as 20 Created and 25 Created by). |
| `classes[].associated_property_defs[].property_def` | `int32` | The ID of the property definition. |
| `classes[].associated_property_defs[].is_required` | `bool` | True if objects of the class must have a value for this property. |
| `classes[].default_workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `classes[].object_type` | `int32` | The ID of the object type the class belongs to. |
| `classes[].name_property_def` | `int32` | The property definition whose value is the object's name: 0 (Name or title) unless the class names its objects by another property. |
| `classes[].force_workflow` | `bool` | True if objects of this class must use `default_workflow`. |
| `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. |
| `classes[].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. |
| `classes[].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. |
| `classes[].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. |
| `classes[].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. |
| `classes[].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. |
| `classes[].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. |
| `classes[].current_user_permissions` | [`ClassPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassPermissionsForClient/index.md) | If set, specifies the permissions for current user that defines the visibility and other permission settings of this class. |
| `classes[].current_user_permissions.can_user_see` | `bool` | The class is visible for the current user. |
| `classes[].current_user_permissions.can_user_attach_objects` | `bool` | The current user can attach new objects to this class. |
| `classes[].object_type_class_content` | [`ObjectTypeSpecificClassContentUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSpecificClassContentUnion/index.md) | Settings that only some object types have; set for the assignment classes of object type 10 (Assignment). |
| `classes[].object_type_class_content.assignment` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) (oneof data) | Assignment-specific class settings. |
| `classes[].is_object_type_default_class` | `bool` | True if this is the default class of its object type. |
| `class_groups[]` | repeated [`ClassGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) | The class groups the user can see, or empty if `known_version` was current. See [ClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md). |
| `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. |
---
# IRPCPropertyDefs.GetObjectClass
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClass/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets one class by ID, with the property definitions associated with it.
- **Service:** [Property definitions and classes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md) `MFiles.IRPCPropertyDefs`
- **gRPC method:** `/MFiles.IRPCPropertyDefs/GetObjectClass`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-class`
- **Request:** [`GetObjectClassRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClass/index.md#request)
- **Response:** [`GetObjectClassResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClass/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Use it to build a metadata card or to check properties before
[AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): the class gives
the required and optional properties (`associated_property_defs`), the property used as the
object's name (`name_property_def`) and the default workflow.
- A class that does not exist, or that the user is not allowed to see, fails with the error
message "Not found.". A deleted class also fails unless `allow_deleted` is true.
- `associated_property_defs` lists only the property definitions the user can see.
- Cacheable by metadata structure version.
## Request: GetObjectClassRequest
> Nested 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 class (an item ID in value list 1, Classes). 0 is the Document class; some built-in classes have negative IDs. |
| `allow_deleted` | `bool` | True to return the class even if it has been deleted. |
## Response: GetObjectClassResponse
> 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 |
|---|---|---|
| `object_class` | [`ObjectClass`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClass/index.md) | The class. See [ObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClass/index.md). |
| `object_class.base_info` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The class as an item of value list 1 (Classes). The class ID is `base_info.item_info.obj_id.item_id.internal_id` and its name `base_info.item_info.name`. |
| `object_class.base_info.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. |
| `object_class.base_info.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `object_class.base_info.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `object_class.base_info.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `object_class.base_info.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `object_class.base_info.owner_name` | `string` | The name of the owner item. |
| `object_class.base_info.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. |
| `object_class.base_info.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. |
| `object_class.associated_property_defs[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | The properties of objects of this class, each with `is_required`. Lists only property definitions the caller can see, and includes the built-in properties that every object has (such as 20 Created and 25 Created by). |
| `object_class.associated_property_defs[].property_def` | `int32` | The ID of the property definition. |
| `object_class.associated_property_defs[].is_required` | `bool` | True if objects of the class must have a value for this property. |
| `object_class.default_workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `object_class.object_type` | `int32` | The ID of the object type the class belongs to. |
| `object_class.name_property_def` | `int32` | The property definition whose value is the object's name: 0 (Name or title) unless the class names its objects by another property. |
| `object_class.force_workflow` | `bool` | True if objects of this class must use `default_workflow`. |
| `object_class.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. |
| `object_class.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. |
| `object_class.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. |
| `object_class.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. |
| `object_class.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. |
| `object_class.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. |
| `object_class.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. |
| `object_class.current_user_permissions` | [`ClassPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassPermissionsForClient/index.md) | If set, specifies the permissions for current user that defines the visibility and other permission settings of this class. |
| `object_class.current_user_permissions.can_user_see` | `bool` | The class is visible for the current user. |
| `object_class.current_user_permissions.can_user_attach_objects` | `bool` | The current user can attach new objects to this class. |
| `object_class.object_type_class_content` | [`ObjectTypeSpecificClassContentUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSpecificClassContentUnion/index.md) | Settings that only some object types have; set for the assignment classes of object type 10 (Assignment). |
| `object_class.object_type_class_content.assignment` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) (oneof data) | Assignment-specific class settings. |
| `object_class.is_object_type_default_class` | `bool` | True if this is the default class of its object type. |
## Related methods
- [IRPCObjectOperations.AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
---
# Value lists (IRPCValueLists)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/
Reads value lists and their items, and lets users add and edit value list items and traditional
folders.
- **gRPC service:** `MFiles.IRPCValueLists`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 17
- **Proto file:** [`mfiles/IRPCValueLists.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCValueLists.proto)
## Overview
Use it to fill lookup controls and to read or maintain the items of value lists. The service is
not read-only: the remarks of its write methods list the vault rights they need. For how value
lists relate to object types, classes and properties, see
[Vault and metadata structure](https://developer.m-files.com/APIs/gRPC-API/concepts/vault-and-metadata-structure/index.md);
for keeping a cached list current, see
[Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).
- **List the value lists** (and object types) of the vault:
[GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md),
[GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md).
- **Candidate values for lookup properties** (lookup control, autocomplete), several lists per
call: [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md).
- **Find items of one list** by name, ID, owner, parent or deleted state:
[SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md).
- **Keep a local copy of a list** up to date with deltas:
[GetValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md).
- **The user's recently used values** of a lookup property:
[GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md).
- **Add, update or undelete an item**:
[AddValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md),
[UpdateValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/index.md),
[UndeleteValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/index.md).
- **Traditional folders**:
[CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md),
[RenameValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/index.md),
[RemoveValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/index.md),
[RemoveOrDestroyTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md),
[ChangeValueListItemPermissionsFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/index.md).
- **Permissions of an item**:
[GetValueListItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md),
[CheckAccessToValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/index.md).
**IDs.** Value lists and object types share one ID space: an object type is a value list whose
items are objects (`ValueList.is_real_object_type`). The item calls accept both, so
[GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) returns customers for object type
136 just as it returns countries for value list 154. An item is identified by an
[ObjID](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md): `type` is the value list ID and `item_id.internal_id` the item
ID. Item IDs are unique only within one list. Lookup property values
([PropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) with `is_based_on_value_list`) point to items of
`PropertyDef.value_list`. Built-in lists keep their IDs in every vault, for example 1 Classes,
2 Class groups, 4 Traditional folders, 6 Users, 7 Workflows, 8 Workflow states, 16 User groups.
**Item search conditions.** The `search_conditions` of the item searches are
[SearchCondition](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md)s whose expression is a property value
(`EXPRESSION_TYPE_PROPERTY_VALUE`) on one of these pseudo property definition IDs. They exist
only in item searches; ordinary property definitions are rejected with "Invalid search
condition.". Conditions are combined with AND.
| ID | Item field | Value (`TypedValue`) | Example condition type |
| --- | --- | --- | --- |
| 1 | Item ID | `DATATYPE_INTEGER` | `CONDITION_TYPE_EQUAL` |
| 2 | Name | `DATATYPE_TEXT` | `CONDITION_TYPE_CONTAINS`, `CONDITION_TYPE_STARTS_WITH` (case-insensitive) |
| 3 | Owner item | `DATATYPE_LOOKUP` (`lookup.value_list_item_info.obj_id` = owner item) | `CONDITION_TYPE_EQUAL` |
| 4 | Parent item | `DATATYPE_INTEGER`, or unset for top-level items | `CONDITION_TYPE_EQUAL` |
| 5 | Deleted | `DATATYPE_BOOLEAN` | `CONDITION_TYPE_EQUAL` |
| 6 | Object type | `DATATYPE_INTEGER` | `CONDITION_TYPE_EQUAL` |
| 7 | External (display) ID | `DATATYPE_TEXT` | `CONDITION_TYPE_EQUAL` |
| 8 | GUID | `DATATYPE_TEXT` (with braces) | `CONDITION_TYPE_EQUAL` |
To search objects by their properties, use [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md)
instead. Item lists are not covered by the metadata structure version: adding or changing items does not
change the `mfiles-metadata-version-bin` trailer, so do not cache items by it.
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md) | Gets one value list or object type by ID, without its icon. | `write` `session or assertion` `returns metadata structure version` |
| [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) | Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [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. | `write` `session or assertion` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [ChangeValueListItemPermissionsFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/index.md) | Changes the permissions of a traditional folder. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [CheckAccessToValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/index.md) | Checks whether the calling user has the given access under an access control list that the caller supplies. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [CreateFolderTree](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateFolderTree/index.md) | Creates a tree of traditional folders under one anchor in one transaction: either every folder is created or the call fails and nothing is saved. | `write` `session or assertion` `returns metadata structure version` |
| [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md) | Creates a traditional folder, or returns an existing folder with the same name. | `write` `session or assertion` `returns metadata structure version` |
| [GetValueListItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md) | Gets the permissions of one item of a plain value list. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md) | Gets the values that the calling user has most recently used for a lookup property. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md) | Gets the items of one value list or object type, or only the changes since a known version. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [RemoveOrDestroyTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md) | Deletes or destroys a traditional folder and everything in it. | `write` `session or assertion` `returns metadata structure version` |
| [RemoveValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/index.md) | Deletes a traditional folder (marks it deleted). | `write` `session or assertion` `returns metadata structure version` |
| [RenameValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/index.md) | Renames a traditional folder. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [UndeleteValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/index.md) | Restores a deleted item of a plain value list, together with its deleted parent items. | `write` `session or assertion` |
| [UpdateValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/index.md) | Updates an item of a plain value list or a traditional folder, as a user. | `write` `session or assertion` `returns metadata structure version` |
---
# IRPCValueLists.GetValueLists
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all value lists of the vault, including the object types, without icons.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetValueLists`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-lists`
- **Request:** [`GetValueListsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md#request)
- **Response:** [`GetValueListsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Returns plain value lists (such as Classes, Users or Country) **and** real object types; use
`is_real_object_type` to tell them apart. `icon` is always empty here; get icons with
[GetObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md).
- Lists that the user is not allowed to see are returned with empty `name_singular` and
`name_plural` and `object_type_permissions.can_user_see` false.
- `options.can_add_items` and `object_type_permissions.can_user_add_new_items` together tell
whether [AddValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md)
can add items to the list for this user.
- Names are in the session language when the vault has translations for it.
- Cacheable by metadata structure version. Returns the lists only, not their items: get items with
[GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md).
## Request: GetValueListsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
## Response: GetValueListsResponse
> 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 |
|---|---|---|
| `value_lists[]` | repeated [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | All value lists and object types, including those the user cannot see (with empty names). See [ValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md). |
| `value_lists[].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. |
| `value_lists[].name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `value_lists[].name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `value_lists[].icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `value_lists[].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). |
| `value_lists[].is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `value_lists[].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. |
| `value_lists[].owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `value_lists[].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. |
| `value_lists[].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). |
| `value_lists[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `value_lists[].options.can_have_files` | `bool` | Can objects have files? |
| `value_lists[].options.can_add_items` | `bool` | True if new items (value lists) or new objects (object types) can be added. The caller also needs `ValueList.object_type_permissions.can_user_add_new_items`. |
| `value_lists[].options.is_external` | `bool` | True if the list is marked external. Built-in lists such as Users (6), Workflows (7) and User groups (16) also have this flag. |
| `value_lists[].options.show_new_object_command_in_task_pane` | `bool` | Show the creation command for this type in the task pane? |
| `value_lists[].options.is_external_connection_disabled` | `bool` | Is external connection currently disabled? |
| `value_lists[].options.is_translatable` | `bool` | Can the contents of value list or object type be translated? |
| `value_lists[].options.is_separate_property_storage` | `bool` | True if the object type has its own storage of property values for searches. |
| `value_lists[].options.disallow_as_grouping_level` | `bool` | Is using this object type as a grouping level in views disallowed? |
| `value_lists[].options.basic` | `bool` | Is basic tier object type? |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `value_lists[].targets_for_browsing[].target_object_type` | `int32` | The ID of the target object type. |
| `value_lists[].targets_for_browsing[].view` | `int32` | The ID of the view collection where instances of the target object type are being browsed. This view collection resides in the predefined Built-in Views view folder. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].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. |
| `value_lists[].object_type_permissions.can_user_see` | `bool` | The object type is visible for the current user (provided for symmetry). |
| `value_lists[].object_type_permissions.can_user_add_new_items` | `bool` | The current user can add new items. |
| `value_lists[].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). |
| `value_lists[].default_acl_for_objects.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. |
| `value_lists[].default_acl_for_objects.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. |
| `value_lists[].default_acl_for_objects.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `value_lists[].default_acl_for_objects.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. |
| `value_lists[].default_acl_for_objects.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. |
| `value_lists[].default_acl_for_objects.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. |
| `value_lists[].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). |
| `value_lists[].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. |
| `value_lists[].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). |
| `value_lists[].preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `value_lists[].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. |
| `value_lists[].search_characteristics.exclude_in_entire_file_data_search` | `bool` | Specifies whether object type is excluded from file content searches. |
| `value_lists[].search_characteristics.exclude_in_entire_meta_data_search` | `bool` | Specifies whether object type is excluded from metadata searches. |
| `value_lists[].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. |
| `value_lists[].indexing_definition.indexed_value_lists[]` | repeated `int32` | IDs of indexed value lists. |
| `value_lists[].indexing_definition.indexed_properties[]` | repeated `int32` | IDs of indexed properties. |
| `value_lists[].view_id` | `int32` | The ID of the object type specific view. |
## 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.
- [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.
- [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md): Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls.
---
# IRPCValueLists.GetValueList
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets one value list or object type by ID, without its icon.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetValueList`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-list`
- **Request:** [`GetValueListRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md#request)
- **Response:** [`GetValueListResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Accepts both value list IDs and object type IDs. An unknown ID fails with "Not found.".
- A list the user cannot see is returned with empty names; it does not fail.
- Cacheable by metadata structure version. Same data as
[GetObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/index.md) without the icon.
## Request: GetValueListRequest
> Nested 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 or object type. |
## Response: GetValueListResponse
> 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 |
|---|---|---|
| `object_type_basic` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | The value list. See [ValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md). |
| `object_type_basic.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_type_basic.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `object_type_basic.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `object_type_basic.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_type_basic.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_type_basic.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `object_type_basic.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_type_basic.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `object_type_basic.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_type_basic.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_type_basic.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_type_basic.options.can_have_files` | `bool` | Can objects have files? |
| `object_type_basic.options.can_add_items` | `bool` | True if new items (value lists) or new objects (object types) can be added. The caller also needs `ValueList.object_type_permissions.can_user_add_new_items`. |
| `object_type_basic.options.is_external` | `bool` | True if the list is marked external. Built-in lists such as Users (6), Workflows (7) and User groups (16) also have this flag. |
| `object_type_basic.options.show_new_object_command_in_task_pane` | `bool` | Show the creation command for this type in the task pane? |
| `object_type_basic.options.is_external_connection_disabled` | `bool` | Is external connection currently disabled? |
| `object_type_basic.options.is_translatable` | `bool` | Can the contents of value list or object type be translated? |
| `object_type_basic.options.is_separate_property_storage` | `bool` | True if the object type has its own storage of property values for searches. |
| `object_type_basic.options.disallow_as_grouping_level` | `bool` | Is using this object type as a grouping level in views disallowed? |
| `object_type_basic.options.basic` | `bool` | Is basic tier object type? |
| `object_type_basic.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_type_basic.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_type_basic.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_type_basic.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_type_basic.targets_for_browsing[].target_object_type` | `int32` | The ID of the target object type. |
| `object_type_basic.targets_for_browsing[].view` | `int32` | The ID of the view collection where instances of the target object type are being browsed. This view collection resides in the predefined Built-in Views view folder. |
| `object_type_basic.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_type_basic.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. |
| `object_type_basic.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. |
| `object_type_basic.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. |
| `object_type_basic.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. |
| `object_type_basic.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. |
| `object_type_basic.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. |
| `object_type_basic.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_type_basic.object_type_permissions.can_user_see` | `bool` | The object type is visible for the current user (provided for symmetry). |
| `object_type_basic.object_type_permissions.can_user_add_new_items` | `bool` | The current user can add new items. |
| `object_type_basic.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_type_basic.default_acl_for_objects.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. |
| `object_type_basic.default_acl_for_objects.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. |
| `object_type_basic.default_acl_for_objects.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `object_type_basic.default_acl_for_objects.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. |
| `object_type_basic.default_acl_for_objects.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. |
| `object_type_basic.default_acl_for_objects.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. |
| `object_type_basic.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_type_basic.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_type_basic.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_type_basic.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `object_type_basic.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_type_basic.search_characteristics.exclude_in_entire_file_data_search` | `bool` | Specifies whether object type is excluded from file content searches. |
| `object_type_basic.search_characteristics.exclude_in_entire_meta_data_search` | `bool` | Specifies whether object type is excluded from metadata searches. |
| `object_type_basic.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_type_basic.indexing_definition.indexed_value_lists[]` | repeated `int32` | IDs of indexed value lists. |
| `object_type_basic.indexing_definition.indexed_properties[]` | repeated `int32` | IDs of indexed properties. |
| `object_type_basic.view_id` | `int32` | The ID of the object type specific view. |
## Related methods
- [IRPCObjectTypes.GetObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectType/index.md): Gets one object type or value list by ID, with its icon.
- [GetValueListItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md): Gets the permissions of one item of a plain value list.
- [GetValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md): Gets the items of one value list or object type, or only the changes since a known version.
- [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md): Gets the values that the calling user has most recently used for a lookup property.
---
# IRPCValueLists.GetLookupItems
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the selectable items of one or more value lists or object types in one call, for example
to fill lookup controls.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetLookupItems`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-lookup-items`
- **Request:** [`GetLookupItemsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md#request)
- **Response:** [`GetLookupItemsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed; items the user is not allowed
to see are left out.
- One [LookupItemRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemRequest/index.md) per list. The response has one
[LookupItemResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemResponse/index.md) per request, in request order;
identical requests are run once and their result copied.
- **Deleted items are left out** unless a request has the condition Deleted (5) equal to true,
in which case only deleted items are returned. This differs from
[SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md).
- Set `LookupItemRequest.property_def` to the lookup property being edited to apply that
property's value filter (`PropertyDef.value_list_item_filter`); use -1 for no filter.
- `results_limit` unset or 0 returns all matching items. When a list has more items than the
limit, `has_more_results` is true; narrow the search with a name condition instead of paging
(there is no offset).
- In hierarchical lists, the parents of matching items are returned too, so a response can
contain more items than `results_limit`.
- The order of the items is not specified; sort on the client.
- If any request names an unknown list, the whole call fails with "Not found.".
- For external lists, `external_data_source_refresh` can refresh the list from its external
database before the read. Not cacheable: item lists change without a metadata structure version change.
- Related: [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md)
for the user's recently used values.
## Request: GetLookupItemsRequest
Request for getting lookup items of multiple object types or value lists (lookup types).
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `requests[]` | repeated [`LookupItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemRequest/index.md) | One request per value list or object type. See [LookupItemRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemRequest/index.md). |
| `requests[].external_data_source_refresh` | [`ExtDBRefreshType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtDBRefreshType/index.md) | For a list connected to an external database: whether to refresh it from the database before the read. `EXT_DBREFRESH_TYPE_NONE` reads the items the vault already has. Values: `EXT_DBREFRESH_TYPE_NONE` (0), `EXT_DBREFRESH_TYPE_QUICK` (1), `EXT_DBREFRESH_TYPE_FULL` (2). |
| `requests[].value_list_id` | `int32` | The ID of the value list or object type whose items are wanted. |
| `requests[].property_def` | `int32` | The ID of the lookup property being edited, to apply its value filter (`PropertyDef.value_list_item_filter`), or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition ID (Name or title). |
| `requests[].search_conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | Item conditions, combined with AND, on the item pseudo properties 1-8 (for example 2 = name); see the [IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) overview. Deleted items are left out unless the condition Deleted (5) equal to true is given. |
| `requests[].search_conditions[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `requests[].search_conditions[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `requests[].search_conditions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `requests[].results_limit` | optional `uint32` | The maximum number of items to return. Unset or 0 returns all. |
| `resolve_current_user_placeholders` | `bool` | True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID. |
| `include_permissions` | `bool` | True to fill `acl` and `current_user_permissions` of each returned item. Leave false if you need only IDs and names. |
| `timeout_in_seconds` | `uint32` | 0 for no timeout. Otherwise the server checks the elapsed time between the steps of the call and fails it with a timeout error once the limit has passed. |
## Response: GetLookupItemsResponse
Search multiple object type items 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 |
|---|---|---|
| `lookup_item_results[]` | repeated [`LookupItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemResponse/index.md) | One result per request, in the order of `requests`. |
| `lookup_item_results[].value_list_id` | `int32` | The `value_list_id` of the request. |
| `lookup_item_results[].items[]` | repeated [`ValueListItemData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemData/index.md) | The matching items, with permissions if the request had `include_permissions`. In hierarchical lists the parents of matching items are included. |
| `lookup_item_results[].items[].item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The item. See [ValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md). |
| `lookup_item_results[].items[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The access control list of the item. Set only when the request had `include_permissions`. |
| `lookup_item_results[].items[].current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | What the caller may do with the item. Set only when the request had `include_permissions`. |
| `lookup_item_results[].has_more_results` | `bool` | True if more items matched than `results_limit` allowed. |
## Related methods
- [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.
- [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md): Gets the values that the calling user has most recently used for a lookup property.
---
# IRPCValueLists.SearchValueListItemsWithPermissions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Searches the items of one value list or object type by item ID, name, owner, parent or deleted
state.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-value-list-items-with-permissions`
- **Request:** [`SearchValueListItemsWithPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md#request)
- **Response:** [`SearchValueListItemsWithPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed; items the user is not allowed
to see are left out.
- Works for plain value lists and for real object types (whose items are objects). For the
supported conditions, see the item search conditions table in the
[IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) overview. Property values of objects cannot
be searched here: use [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md).
- **Deleted items are included** by default and flagged with `item_info.options.is_deleted`.
Add the condition Deleted (5) equal to false to get only existing items, or equal to true for
only deleted ones. [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) leaves
deleted items out by default.
- `results_limit` 0 returns all matching items. With a limit, `has_more_results` tells whether
more items matched; there is no paging.
- In hierarchical lists, the parents of matching items are returned too.
- With `include_permissions`, `item_acls` and `item_current_user_permissions` have one entry
per item, in the order of `items`.
- The order of the items is not specified.
- An unknown list fails with "Not found.". Not cacheable.
## Request: SearchValueListItemsWithPermissionsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `external_data_source_refresh` | [`ExtDBRefreshType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtDBRefreshType/index.md) | For a list connected to an external database: whether to refresh it from the database before the search. `EXT_DBREFRESH_TYPE_NONE` reads the items the vault already has. Values: `EXT_DBREFRESH_TYPE_NONE` (0), `EXT_DBREFRESH_TYPE_QUICK` (1), `EXT_DBREFRESH_TYPE_FULL` (2). |
| `value_list` | `int32` | The ID of the value list or object type to search. |
| `filtering_property_def` | `int32` | The ID of a lookup property definition whose value filter (`PropertyDef.value_list_item_filter`) is applied, or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition ID (Name or title). |
| `search_conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | Conditions on the item pseudo properties 1-8 (see the service overview), combined with AND. Empty returns all items, deleted ones included. |
| `search_conditions[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `search_conditions[].expression.type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `search_conditions[].expression.data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `search_conditions[].expression.indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `search_conditions[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `search_conditions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `search_conditions[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `search_conditions[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `search_conditions[].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. |
| `resolve_current_user_placeholders` | `bool` | True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID. |
| `include_permissions` | `bool` | True to fill `item_acls` and `item_current_user_permissions`. |
| `results_limit` | `uint32` | The maximum number of items to return; 0 returns all. |
## Response: SearchValueListItemsWithPermissionsResponse
> 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 |
|---|---|---|
| `items[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The matching items. See [ValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md). |
| `items[].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. |
| `items[].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. |
| `items[].item_info.name` | `string` | The name of the item. |
| `items[].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). |
| `items[].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. |
| `items[].item_info.guid` | `string` | GUID for the item. |
| `items[].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). |
| `items[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `items[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `items[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `items[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `items[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `items[].owner_name` | `string` | The name of the owner item. |
| `items[].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. |
| `items[].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. |
| `items[].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. |
| `items[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `items[].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. |
| `items[].icon.value` | `bytes` | Array of bytes. |
| `item_acls[]` | repeated [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | With `include_permissions`, the access control list of each item, in the order of `items`; otherwise empty. |
| `item_acls[].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. |
| `item_acls[].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. |
| `item_acls[].custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `item_acls[].custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `item_acls[].custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `item_acls[].custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `item_acls[].custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `item_acls[].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. |
| `item_acls[].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. |
| `item_acls[].custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `item_acls[].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. |
| `item_acls[].restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `item_acls[].restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `item_acls[].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. |
| `item_acls[].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. |
| `item_acls[].additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `item_acls[].additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `item_current_user_permissions[]` | repeated [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | With `include_permissions`, what the caller may do with each item, in the order of `items`; otherwise empty. |
| `item_current_user_permissions[].can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `item_current_user_permissions[].can_user_edit` | `bool` | The current user can edit the object. |
| `item_current_user_permissions[].can_user_delete` | `bool` | The current user can delete the object. |
| `item_current_user_permissions[].can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `has_more_results` | `bool` | True if more items matched than `results_limit` allowed. |
## Related methods
- [IRPCSearch.SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md): Searches the vault for objects that match the given conditions.
- [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md): Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls.
---
# IRPCValueLists.AddValueListItemFromClient
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Adds a new item to a value list, as a user.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/AddValueListItemFromClient`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-value-list-item-from-client`
- **Request:** [`AddValueListItemFromClientRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md#request)
- **Response:** [`AddValueListItemFromClientResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session whose user has the vault rights `manage_value_list_items_from_client`
and `license_allows_modifications` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); otherwise the
call fails with "Access denied.".
- The list must allow new items (`ValueList.options.can_add_items`), and the user must be
allowed to add items to it (`ValueList.object_type_permissions.can_user_add_new_items`).
Otherwise the call fails with "Access denied." or "You are not allowed to add new values to
the list ...".
- Only plain value lists: a real object type fails with "Not found." (create objects with
[AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md)), and Traditional folders (4) fail
with "The parameter is incorrect." (use
[CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md)).
- The name must not be empty. `has_parent` is allowed only in hierarchical lists and
`has_owner` only in lists that are not hierarchical; violations fail with an error.
- The server assigns the item ID and a new GUID; the values you send are ignored. Names do not
have to be unique, so a retried call creates a second item with the same name: search by name
first if the call may be repeated.
- The new item gets the list's default permissions for new items. If the user could not see the
new item, the call fails and nothing is added.
- For a list connected to an external database, the item is also written to that database.
Vault event handlers for new value list items run.
- Adding items does not change the metadata structure version. Remove items with the administration
service ([RemoveObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md));
this service cannot remove items of ordinary value lists.
## Request: AddValueListItemFromClientRequest
> Nested 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 to add. Set `item_info.obj_id.type` to the value list ID and `item_info.name`; for a hierarchical list set `has_parent` and `parent_id`, for a list with an owner list set `has_owner` and `owner_id`. The item ID and GUID are ignored. |
| `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. |
## Response: AddValueListItemFromClientResponse
> Nested 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 new item as stored, with its new item ID and GUID. |
| `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. |
## Related methods
- [IRPCObjectOperations.AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
- [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md): Creates a traditional folder, or returns an existing folder with the same name.
- [IRPCObjectTypesAdmin.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.
---
# IRPCValueLists.ChangeValueListItemPermissionsFromClient
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Changes the permissions of a traditional folder.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-value-list-item-permissions-from-client`
- **Request:** [`ChangeValueListItemPermissionsFromClientRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/index.md#request)
- **Response:** [`ChangeValueListItemPermissionsFromClientResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Works only for Traditional folders (value list 4); other lists fail with "Access denied.".
- Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
and read access to the folder.
- `visible` tells whether the caller can still see the folder under the new permissions.
## Request: ChangeValueListItemPermissionsFromClientRequest
> 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 folder: `type` 4 and the folder's 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. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The new access control list of the folder. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
## Response: ChangeValueListItemPermissionsFromClientResponse
> Nested 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 folder after the change. |
---
# IRPCValueLists.CheckAccessToValueListItem
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Checks whether the calling user has the given access under an access control list that the
caller supplies.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/CheckAccessToValueListItem`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-access-to-value-list-item`
- **Request:** [`CheckAccessToValueListItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/index.md#request)
- **Response:** [`CheckAccessToValueListItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Evaluates the ACL against the user's identity and group memberships, which the caller may not
know. Nothing in the vault is changed.
- `allowed` is unset (false) when the user lacks any of the requested rights.
## Request: CheckAccessToValueListItemRequest
> 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 |
|---|---|---|
| `utf8szacl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The access control list to evaluate, for example one returned by [GetValueListItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md). |
| `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. |
| `required` | [`ObjectAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectAccess/index.md) | The rights to check, for example `read` or `edit`. All of them must be granted. |
| `required.all` | `bool` | Specifies all flags set; Including any future flags. |
| `required.read` | `bool` | Read. |
| `required.edit` | `bool` | Edit. |
| `required.change_permissions` | `bool` | Change security settings. |
| `required.delete_object` | `bool` | Delete. |
| `required.attach_objects` | `bool` | Attach objects. |
## Response: CheckAccessToValueListItemResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `allowed` | `bool` | True if the user has all the `required` rights under the ACL. |
---
# IRPCValueLists.CreateFolderTree
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateFolderTree/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a tree of traditional folders under one anchor in one transaction: either every folder
is created or the call fails and nothing is saved.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/CreateFolderTree`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-folder-tree`
- **Request:** [`CreateFolderTreeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateFolderTree/index.md#request)
- **Response:** [`CreateFolderTreeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateFolderTree/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Not available in this version: the server fails the call with "Not implemented.". Use
[CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md)
for each folder instead.
- Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`.
## Request: CreateFolderTreeRequest
Requests to create a tree of Traditional Folders under one anchor.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `anchor_type` | [`FolderTreeAnchorType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderTreeAnchorType/index.md) | Where the tree is attached. Values: `FOLDER_TREE_ANCHOR_TYPE_UNSPECIFIED` (0), `FOLDER_TREE_ANCHOR_TYPE_TRADITIONAL_ROOT` (1), `FOLDER_TREE_ANCHOR_TYPE_FOLDER` (2), `FOLDER_TREE_ANCHOR_TYPE_VIEW_LOCATION` (3). |
| `anchor_folder_id` | optional `int32` | The ID of the existing folder to create the tree in, as known to the client (the folder the user drops onto). Required for the folder anchor, not allowed for the others. Not the ID of any folder in the request: those are created by the server and returned in the response. |
| `view_location` | [`ViewLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewLocation/index.md) | The anchor view location. Required for the viewLocation anchor, not allowed for the others. |
| `view_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. |
| `view_location.parent_folder[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `view_location.parent_folder[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `view_location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `view_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. |
| `view_location.customized_property_folder.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `view_location.customized_property_folder.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `view_location.customized_property_folder.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. |
| `nodes[]` | repeated [`FolderTreeNode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderTreeNode/index.md) | The folders to create under the anchor, parents before children. |
| `nodes[].name` | `string` | The folder name. |
| `nodes[].parent_index` | `int32` | The index of the parent node in the list, or -1 for a top-level folder. Must be smaller than the node's own index (parents come first). |
| `rename_on_conflict` | `bool` | What to do when a folder name is used by a sibling: false fails the whole request, true gives the folder the name " (n)". |
## Response: CreateFolderTreeResponse
Response to a create folder tree request. Always describes a fully created tree.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `nodes[]` | repeated [`FolderTreeNodeResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderTreeNodeResult/index.md) | One result per submitted folder, in the order of the request. |
| `nodes[].restored` | `bool` | True when a deleted same-named folder was restored, false when a new folder was created. |
| `nodes[].folder_id` | `int32` | The ID of the folder. |
| `nodes[].name` | `string` | The name actually used. |
| `nodes[].renamed` | `bool` | True when the rename policy changed the name. |
| `current_version_on_server` | `int64` | The current version of the Traditional Folders value list's data on the server. |
## Related methods
- [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md): Creates a traditional folder, or returns an existing folder with the same name.
---
# IRPCValueLists.CreateOrFindTraditionalFolder
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a traditional folder, or returns an existing folder with the same name.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-or-find-traditional-folder`
- **Request:** [`CreateOrFindTraditionalFolderRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md#request)
- **Response:** [`CreateOrFindTraditionalFolderResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`.
- The item must be in Traditional folders (`item_info.obj_id.type` 4) and have a name; it cannot
have an owner. Set `has_parent` and `parent_id` for a subfolder.
- Names are compared case-insensitively. A deleted folder with the same name is always
undeleted and returned, whatever `can_return_existing_folder` says.
- The response lists the folder and its parent folders.
## Request: CreateOrFindTraditionalFolderRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `vl_item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The folder to create: `item_info.obj_id.type` 4, `item_info.name`, and for a subfolder `has_parent` and `parent_id`. The item ID is ignored. |
| `vl_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. |
| `vl_item.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. |
| `vl_item.item_info.name` | `string` | The name of the item. |
| `vl_item.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). |
| `vl_item.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. |
| `vl_item.item_info.guid` | `string` | GUID for the item. |
| `vl_item.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). |
| `vl_item.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `vl_item.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `vl_item.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `vl_item.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `vl_item.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `vl_item.owner_name` | `string` | The name of the owner item. |
| `vl_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. |
| `vl_item.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. |
| `vl_item.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. |
| `vl_item.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `vl_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. |
| `vl_item.icon.value` | `bytes` | Array of bytes. |
| `can_return_existing_folder` | `bool` | True to return an existing folder with the same name (compared case-insensitively) instead of failing. |
## Response: CreateOrFindTraditionalFolderResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `putf8szvlitems[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The created or found folder and its parent folders. |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].item_info.name` | `string` | The name of the item. |
| `putf8szvlitems[].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). |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].item_info.guid` | `string` | GUID for the item. |
| `putf8szvlitems[].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). |
| `putf8szvlitems[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `putf8szvlitems[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `putf8szvlitems[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `putf8szvlitems[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `putf8szvlitems[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `putf8szvlitems[].owner_name` | `string` | The name of the owner item. |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `putf8szvlitems[].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. |
| `putf8szvlitems[].icon.value` | `bytes` | Array of bytes. |
| `current_version_on_server` | `int64` | The current version of the Traditional folders list's items (see `GetValueListItemsWithPermissions.known_version`). |
---
# IRPCValueLists.GetValueListItemPermissions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the permissions of one item of a plain value list.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetValueListItemPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-list-item-permissions`
- **Request:** [`GetValueListItemPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md#request)
- **Response:** [`GetValueListItemPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires read access to the item; otherwise fails with an access denied error.
- Not for real object types ("Not found."): get object permissions from
[IRPCObjectOperations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md).
## Request: GetValueListItemPermissionsRequest
> Nested 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. |
## Response: GetValueListItemPermissionsResponse
> 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 |
|---|---|---|
| `putf8szacl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The access control list of the item. |
| `putf8szacl.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. |
| `putf8szacl.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. |
| `putf8szacl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `putf8szacl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `putf8szacl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `putf8szacl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `putf8szacl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `putf8szacl.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. |
| `putf8szacl.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. |
| `putf8szacl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `putf8szacl.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. |
| `putf8szacl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `putf8szacl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `putf8szacl.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. |
| `putf8szacl.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. |
| `putf8szacl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `putf8szacl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `object_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | What the calling user may do with the item. |
| `object_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
## Related methods
- [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md): Gets one value list or object type by ID, without its icon.
---
# IRPCValueLists.GetValueListItemProposals
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the values that the calling user has most recently used for a lookup property.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetValueListItemProposals`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-list-item-proposals`
- **Request:** [`GetValueListItemProposalsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md#request)
- **Response:** [`GetValueListItemProposalsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. Returns at most five items, the most recently used first. Deleted
items and items the user cannot see are left out.
- A property that is not a lookup, or that the user has not used yet, gives an empty list.
- Use it to offer quick picks next to a lookup control filled with
[GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md).
## Request: GetValueListItemProposalsRequest
Request for getting proposed values for a lookup property.
> Nested 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_id` | `uint32` | The ID of the lookup property definition whose recently used values are wanted. |
## Response: GetValueListItemProposalsResponse
Response for getting proposed values for a lookup property.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `proposed_values[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Up to five items, most recently used first. |
| `proposed_values[].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. |
| `proposed_values[].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. |
| `proposed_values[].item_info.name` | `string` | The name of the item. |
| `proposed_values[].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). |
| `proposed_values[].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. |
| `proposed_values[].item_info.guid` | `string` | GUID for the item. |
| `proposed_values[].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). |
| `proposed_values[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `proposed_values[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `proposed_values[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `proposed_values[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `proposed_values[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `proposed_values[].owner_name` | `string` | The name of the owner item. |
| `proposed_values[].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. |
| `proposed_values[].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. |
| `proposed_values[].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. |
| `proposed_values[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `proposed_values[].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. |
| `proposed_values[].icon.value` | `bytes` | Array of bytes. |
## Related methods
- [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md): Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls.
- [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md): Gets one value list or object type by ID, without its icon.
---
# IRPCValueLists.GetValueListItemsWithPermissions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the items of one value list or object type, or only the changes since a known version.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetValueListItemsWithPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-list-items-with-permissions`
- **Request:** [`GetValueListItemsWithPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md#request)
- **Response:** [`GetValueListItemsWithPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed; items the user cannot see are
left out. Deleted items are not returned (except as `removed_items` in a delta).
- Meant for clients that keep a local copy of a list. First call with `known_version` 0 and
store `current_version`. Later, send it back as `known_version` with `allow_delta`:
- unchanged list: same `current_version`, no items;
- changed list: `is_delta` true, `items` has the added and changed items and `removed_items`
the IDs of deleted ones;
- if the server cannot give a delta, `is_delta` is false and `items` is the full list.
- The server limits the number of items (`results_limit` in the response, 5000 by default);
`has_more_results` tells whether the list was cut. For large lists use
[GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) with a name condition.
## Request: GetValueListItemsWithPermissionsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `external_data_source_refresh` | [`ExtDBRefreshType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtDBRefreshType/index.md) | For a list connected to an external database: whether to refresh it from the database first. Values: `EXT_DBREFRESH_TYPE_NONE` (0), `EXT_DBREFRESH_TYPE_QUICK` (1), `EXT_DBREFRESH_TYPE_FULL` (2). |
| `value_list` | `int32` | The ID of the value list or object type. |
| `filtering_property_def` | `int32` | The ID of a lookup property definition whose value filter is applied, or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition. |
| `known_version` | `int64` | The `current_version` from the caller's previous response, or 0 to get the full list. With 0 the server never returns a delta. |
| `allow_delta` | `bool` | True to accept only the changes since `known_version`. |
| `resolve_current_user_placeholders` | `bool` | True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID. |
| `include_permissions` | `bool` | True to fill `item_acls` and `item_current_user_permissions`. |
## Response: GetValueListItemsWithPermissionsResponse
> 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 |
|---|---|---|
| `current_version` | `int64` | The current version of the list's items. Store it and send it as `known_version` next time. It changes when items change, not with the metadata structure version. |
| `is_delta` | `bool` | True if `items` and `removed_items` are only the changes since `known_version`. |
| `removed_items[]` | repeated `int32` | In a delta, the IDs of items deleted since `known_version`; otherwise empty. |
| `items[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The items, or in a delta the added and changed items. |
| `items[].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. |
| `items[].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. |
| `items[].item_info.name` | `string` | The name of the item. |
| `items[].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). |
| `items[].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. |
| `items[].item_info.guid` | `string` | GUID for the item. |
| `items[].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). |
| `items[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `items[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `items[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `items[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `items[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `items[].owner_name` | `string` | The name of the owner item. |
| `items[].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. |
| `items[].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. |
| `items[].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. |
| `items[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `items[].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. |
| `items[].icon.value` | `bytes` | Array of bytes. |
| `item_acls[]` | repeated [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | With `include_permissions`, the access control list of each item, in the order of `items`. |
| `item_acls[].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. |
| `item_acls[].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. |
| `item_acls[].custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `item_acls[].custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `item_acls[].custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `item_acls[].custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `item_acls[].custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `item_acls[].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. |
| `item_acls[].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. |
| `item_acls[].custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `item_acls[].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. |
| `item_acls[].restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `item_acls[].restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `item_acls[].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. |
| `item_acls[].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. |
| `item_acls[].additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `item_acls[].additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `item_current_user_permissions[]` | repeated [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | With `include_permissions`, what the caller may do with each item, in the order of `items`. |
| `item_current_user_permissions[].can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `item_current_user_permissions[].can_user_edit` | `bool` | The current user can edit the object. |
| `item_current_user_permissions[].can_user_delete` | `bool` | The current user can delete the object. |
| `item_current_user_permissions[].can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `has_more_results` | `bool` | True if the list has more items than `results_limit`. |
| `results_limit` | `uint32` | The item limit the server applied (0 when no items were returned). |
## Related methods
- [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md): Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls.
- [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md): Gets one value list or object type by ID, without its icon.
---
# IRPCValueLists.RemoveOrDestroyTraditionalFolder
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Deletes or destroys a traditional folder and everything in it.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-or-destroy-traditional-folder`
- **Request:** [`RemoveOrDestroyTraditionalFolderRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md#request)
- **Response:** [`RemoveOrDestroyTraditionalFolderResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
and read access to the folder.
- With `destroy` true the folder and its contents are destroyed permanently.
## Request: RemoveOrDestroyTraditionalFolderRequest
> Nested 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_structure` | `int32` | Must be 4 (Traditional folders); any other value fails. |
| `folder` | `int32` | The item ID of the folder. |
| `destroy` | `bool` | True to destroy the folder and its contents permanently, false to mark them deleted. |
## Response: RemoveOrDestroyTraditionalFolderResponse
> Nested 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 [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The IDs of the objects that were deleted or destroyed. |
| `objects[].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). |
| `objects[].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`. |
| `objects[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `objects[].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. |
---
# IRPCValueLists.RemoveValueListItemFromClient
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Deletes a traditional folder (marks it deleted).
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/RemoveValueListItemFromClient`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-value-list-item-from-client`
- **Request:** [`RemoveValueListItemFromClientRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/index.md#request)
- **Response:** [`RemoveValueListItemFromClientResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Works only for Traditional folders (value list 4); other lists fail with "Access denied.".
`allow_removing_owned_items` must be false; true also fails with "Access denied.".
- Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
and read access to the folder.
- Related: [RemoveOrDestroyTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md)
also handles the folder's contents.
## Request: RemoveValueListItemFromClientRequest
> Nested 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 folder: `type` 4 and the folder's 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` | Must be false; the server rejects true with "Access denied.". |
## Response: RemoveValueListItemFromClientResponse
No fields.
## Related methods
- [RemoveOrDestroyTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md): Deletes or destroys a traditional folder and everything in it.
---
# IRPCValueLists.RenameValueListItemFromClient
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Renames a traditional folder.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/RenameValueListItemFromClient`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/rename-value-list-item-from-client`
- **Request:** [`RenameValueListItemFromClientRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/index.md#request)
- **Response:** [`RenameValueListItemFromClientResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Works only for Traditional folders (value list 4); other lists fail with "The parameter is
incorrect.". The new name must not be empty.
- Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
and read access to the folder.
## Request: RenameValueListItemFromClientRequest
> Nested 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 folder: `type` 4 and the folder's 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. |
| `new_name` | `string` | The new name; must not be empty. |
## Response: RenameValueListItemFromClientResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `items[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The renamed folder and its parent folders. |
| `items[].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. |
| `items[].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. |
| `items[].item_info.name` | `string` | The name of the item. |
| `items[].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). |
| `items[].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. |
| `items[].item_info.guid` | `string` | GUID for the item. |
| `items[].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). |
| `items[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `items[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `items[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `items[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `items[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `items[].owner_name` | `string` | The name of the owner item. |
| `items[].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. |
| `items[].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. |
| `items[].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. |
| `items[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `items[].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. |
| `items[].icon.value` | `bytes` | Array of bytes. |
| `current_version_on_server` | `int64` | The current version of the Traditional folders list's items. |
---
# IRPCValueLists.UndeleteValueListItem
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/
Badges: `Vault API / core` `write` `session or assertion`
Restores a deleted item of a plain value list, together with its deleted parent items.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/UndeleteValueListItem`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/undelete-value-list-item`
- **Request:** [`UndeleteValueListItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/index.md#request)
- **Response:** [`UndeleteValueListItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `license_allows_modifications` and
`manage_value_list_items_from_client` (for Traditional folders: `manage_traditional_folders`).
- Not for real object types: they fail with "Not found."; undelete objects with
[UndeleteObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md).
- Find deleted items with the condition Deleted (5) equal to true in
[SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md).
## Request: UndeleteValueListItemRequest
> Nested 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. |
## Response: UndeleteValueListItemResponse
No fields.
## Related methods
- [IRPCObjectOperations.UndeleteObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md): Undeletes a previously removed object.
- [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.
---
# IRPCValueLists.UpdateValueListItemFromClient
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Updates an item of a plain value list or a traditional folder, as a user.
- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/UpdateValueListItemFromClient`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-value-list-item-from-client`
- **Request:** [`UpdateValueListItemFromClientRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/index.md#request)
- **Response:** [`UpdateValueListItemFromClientResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `license_allows_modifications` and
`manage_value_list_items_from_client` (for Traditional folders, list 4:
`manage_traditional_folders`), and read access to the item.
- Not for real object types ("Not found."), the Classes list (1) or the Class groups list (2)
("The parameter is incorrect."), or lists whose `options.is_external` is set (this includes
built-in lists such as Users and Workflows).
- Send the complete item: read it first (for example with
[SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md)),
change what you need and send it back.
- The response echoes the item you sent; fields you left out (such as the GUID) come back
empty even though the stored values are unchanged. Re-read the item if you need them.
## Request: UpdateValueListItemFromClientRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `vl_item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The complete item, identified by `item_info.obj_id` (value list ID and item ID). |
| `vl_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. |
| `vl_item.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. |
| `vl_item.item_info.name` | `string` | The name of the item. |
| `vl_item.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). |
| `vl_item.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. |
| `vl_item.item_info.guid` | `string` | GUID for the item. |
| `vl_item.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). |
| `vl_item.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `vl_item.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `vl_item.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `vl_item.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `vl_item.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `vl_item.owner_name` | `string` | The name of the owner item. |
| `vl_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. |
| `vl_item.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. |
| `vl_item.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. |
| `vl_item.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `vl_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. |
| `vl_item.icon.value` | `bytes` | Array of bytes. |
## Response: UpdateValueListItemFromClientResponse
> Nested 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 sent in the request. |
| `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. |
## Related methods
- [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.
---
# Search (IRPCSearch)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/
An interface for performing searches.
All search operations can be done via this interface.
- **gRPC service:** `MFiles.IRPCSearch`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 14
- **Proto file:** [`mfiles/IRPCSearch.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCSearch.proto)
## Overview
Use this service to find objects by conditions, to count them, and to browse views the way the
M-Files clients do.
| Job | Method |
| --- | --- |
| Find objects that match conditions | [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md) |
| Count matching objects without fetching them | [GetObjectCountInSearch](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/index.md) |
| Browse views, view levels and their objects | [GetFolderContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md) |
| Facet counts for a full-text search UI | [GetFacetValues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/index.md) |
The other methods serve specific M-Files client features (hit highlighting, listing counts,
notification badges, pinboard, Aino Search and summaries).
**Condition model.** A search is a [SearchConditionArray](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md);
all of its conditions must match (AND). `SearchObjects` and `GetObjectCountInSearch` accept
exactly one array: an empty request or two or more arrays fail with "The parameter is incorrect."
To match one of several values of a lookup, use `CONDITION_TYPE_EQUAL` with a multi-select lookup
value that lists them; for other OR cases, run one search per alternative.
An array with no conditions matches every object the caller can see.
**What a search returns.**
- Only objects the caller is allowed to see: the same search returns fewer objects for a normal
user than for a vault administrator.
- Deleted objects too, for callers who may see deleted objects (vault administrators, for
example), unless the array contains the "not deleted" condition: a `STATUS_TYPE_IS_DELETED`
status value `CONDITION_TYPE_EQUAL` to Boolean `false`. Add it to every search.
- One version per object: the latest checked-in version, or the checked-out version when the
object is checked out to the caller.
- Object and version information without the property values. Read the properties with
[GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md).
**Limits and timeouts.** In `SearchObjects`, `limit` and `timeout_in_seconds` left at 0 mean no
limit and no timeout; the server does not apply a default. Set both. A vault administrator can
configure forced maxima that cap both values. `GetObjectCountInSearch` counts up to 10,000
objects by default and reports larger counts as "more than".
**Errors.** Search errors arrive with gRPC status `UNKNOWN` and the M-Files error message as the
status details, for example "Invalid search condition." for a condition the server cannot
evaluate.
The [Search concept](https://developer.m-files.com/APIs/gRPC-API/concepts/search/index.md) shows the
conditions you need most as complete messages, and the
[paging guide](https://developer.m-files.com/APIs/gRPC-API/guides/paging/index.md) reads a large result
set page by page.
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md) | Searches the vault for objects that match the given conditions. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectCountInSearch](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/index.md) | Counts the objects that match the given conditions without returning them. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetFacetValues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/index.md) | Retrieves the facet values for the documents that satisfy the specified search conditions. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetFolderContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md) | Lists the contents of a view or a view level: subviews, grouping folders and objects. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [CreateSummarization](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/CreateSummarization/index.md) | Creates an Aino summary for the M-Files clients. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetFolderContentsOfPinboard](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOfPinboard/index.md) | Gets the contents of the Pinboard items. | `write` `session or assertion` `returns metadata structure version` |
| [GetFolderContentsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOrDelta/index.md) | Gets the contents of the specified folder, or a delta that indicates changes to document vault data since the logical timestamp known by the caller. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetFolderObjectsCount](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderObjectsCount/index.md) | Gets the count of objects in the specified folder. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectsCountForNotifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectsCountForNotifications/index.md) | Gets the objects count for notification badge. | `read` `session or assertion` `idempotent` |
| [GetPrefillProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetPrefillProperties/index.md) | Gets the property values that a new object created in the given folder gets from that folder. | `read` `session or assertion` `idempotent` |
| [GetSearchHits](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetSearchHits/index.md) | Finds the words of a text that a full-text search condition matches, for hit highlighting. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [QuerySearchAgent](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/QuerySearchAgent/index.md) | Runs an Aino Search query for the M-Files clients. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [SearchReferencedValueListItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchReferencedValueListItems/index.md) | Gets value list items that are referenced by one or more documents (possibly limiting the set of documents with conditions) in ID order. | `write` `session or assertion` |
| [SearchViewLevelFolders](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchViewLevelFolders/index.md) | The search covers the folders that the listing of the level would show without the folder limit. The results can be saved as part of the user's folder selection. Fails with E_NOTIMPL when the feature is not enabled on the server. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
---
# IRPCSearch.SearchObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Searches the vault for objects that match the given conditions.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/SearchObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-objects`
- **Request:** [`SearchObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md#request)
- **Response:** [`SearchObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Results are filtered by the caller's permissions. See the service overview for the condition
model and for what a result contains.
**Order.** Without `sorting`, results are ranked by relevance (`SearchResultsItem.score`);
`SearchFlags.disable_relevancy_ranking` turns ranking off. `sorting` takes one rule; see
[SortRule](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRule/index.md) for the supported keys.
**Paging.** `page_requests` is not supported. To read a large result set in pages, sort by
object ID (sort key -102, ascending) and repeat the search with an extra
`STATUS_TYPE_OBJECT_ID` condition `CONDITION_TYPE_GREATER_THAN` the last object ID received,
until `has_more_results` is false. This works with database conditions only: object ID sorting
cannot be combined with a full-text (any-field) condition.
**Full-text search.** Add an `EXPRESSION_TYPE_ANY_FIELD` condition with `CONDITION_TYPE_CONTAINS`
and a text value. Its [FTSFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FTSFLAGS/index.md) must set `search_metadata`,
`search_filedata` or both; without either the call fails with "Invalid search condition.", and an
empty text fails with "The search request contained no text".
**Aino (semantic) search.** Setting `FTSFLAGS.search_aino` on the any-field condition runs the
search against the vault's enabled Aino index; `target` is then ignored. If the vault has no
enabled Aino index, the call fails with "An enabled Aino index must be present to make an Aino
Search." An Aino result carries the object ID, the title, one file ID, `score` and the matching
text passage in `chunk`. The other fields of `object` are not filled: Aino results do not carry
the class (`class_id` 0 does not mean the Document class) or the object version, and the file
version is reported as 1. Read the object with
[GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md)
before using those values. An Aino search that also has a `STATUS_TYPE_OBJECT_TYPE` condition
returns no results; filter by class or properties instead.
## Request: SearchObjectsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `target` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | The search index and search mode. Leave unset to use the vault's default index and `SEARCH_MODE_DEFAULT`. An unknown index name fails with "Target index is not available." |
| `target.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `target.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `target.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `target.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `conditions[]` | repeated [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | Exactly one condition array; all of its conditions must match. An empty array matches every object the caller can see, deleted objects included. No array or more than one array fails with "The parameter is incorrect." |
| `conditions[].value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `conditions[].value[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `conditions[].value[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `conditions[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `options` | [`SearchFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md) | Search flags. Unset searches the latest versions of all object types as one relevance-ranked list. See [SearchFlags](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md). |
| `options.all` | `bool` | All flags set, including any future flags. Do not use in searches. |
| `options.look_in_all_versions` | `bool` | Also match older versions; each object is returned once. Cannot be combined with `sorting`, and `GetObjectCountInSearch` rejects it. |
| `options.return_latest_visible_version` | `bool` | Return the latest visible version for each matching document. |
| `options.separately_search_in_each_object_type` | `bool` | Search each object type separately and merge the results. The `limit` then applies to each object type, and `pages_with_more_results` lists the object types whose results were cut. |
| `options.allow_quick_refresh_for_external_object_types` | `bool` | If a search with an external ID condition on an external object type finds nothing, refresh the object type from its external database and search again. |
| `options.disable_relevancy_ranking` | `bool` | Do not rank the results by relevance. |
| `options.separately_search_specific_object_types` | `bool` | Allows only specified object types to be searched separately. |
| `options.include_unmanaged_objects` | `bool` | Extends the search to include unmanaged objects. |
| `options.individual_limit_for_each_external_repository` | `bool` | Ensures that up to the specified maximum number of results are returned from each repository. |
| `page_requests[]` | repeated [`SearchResultsPageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsPageRequest/index.md) | Not supported. Must be empty; otherwise the call fails with "Not implemented." |
| `page_requests[].object_type` | `int32` | The identifier of a search results group. |
| `page_requests[].page` | `int32` | The zero-based index of a page. |
| `page_requests[].options` | [`SRPREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRPREQUESTFLAGS/index.md) | Search results page request flags. |
| `page_requests[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `page_requests[].options.unseen_page` | `bool` | If available, the page request is for an unseen page. |
| `page_requests[].options.ignore_original_conditions` | `bool` | If available, the original conditions are ignored. This can be used when including ObjIDs. Do not use with SRPREQUEST_UNSEENPAGE. |
| `page_requests[].options.seen_page` | `bool` | If available, the page request is for an already seen page. |
| `page_requests[].options.initial_page` | `bool` | If available, the page request is initial and for an unseen page. Do not use with SRPREQUEST_SEENPAGE. |
| `page_requests[].seen_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | An array of ObjIDs. If the SRPREQUEST_UNSEENPAGE flag is available, these are ObjIDs to exclude. If the SRPREQUEST_SEENPAGE flag is available, these are ObjIDs to include. |
| `page_requests[].seen_objects[].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). |
| `page_requests[].seen_objects[].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`. |
| `limit` | `uint32` | The maximum number of results. 0 means no limit: the server does not apply a default, only a maximum that the vault administrator may have configured. With `separately_search_in_each_object_type` the limit applies to each object type, and the values 200 and 500 select the server default of 50 results per object type. With `sorting` and 0, at most 20,000 results (a vault setting) are sorted. |
| `timeout_in_seconds` | `uint32` | The search timeout in seconds. 0 means no timeout. A maximum configured for the vault caps larger values and replaces 0. A search that times out fails. |
| `facet_filter` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | If set, specifies the additional facet search filter. |
| `facet_filter.value` | `string` | String. |
| `sorting` | [`SearchResultsSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsSorting/index.md) | How to sort the results. Unset sorts by relevance. At most one rule; see [SearchResultsSorting](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsSorting/index.md). |
| `sorting.rules` | [`SortRuleValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRuleValueArray/index.md) | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
| `sorting.rules.values[]` | repeated [`SortRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRule/index.md) | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
| `sorting.options` | [`SortFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortFlags/index.md) | Sort flags. Set `allow_resorting_to_default_sort` to get relevance order instead of an error when the rule cannot be applied. |
| `sorting.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `sorting.options.allow_resorting_to_default_sort` | `bool` | Allows resorting to default sorting if the specified sorting is not supported. If this flag is not present, an unsupported sort request causes an error. |
## Response: SearchObjectsResponse
> Nested 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 [`SearchResultsItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsItem/index.md) | The matching objects, at most `limit`. Each item has the object and version information but not the property values. |
| `results[].object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
| `results[].object.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `results[].object.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `results[].score` | `int32` | The relevance score of the result. Higher is more relevant. |
| `results[].chunk` | `string` | For an Aino search, the passage of text that matched. Empty for other searches. |
| `has_more_results` | `bool` | True if more objects match than were returned. |
| `pages_with_more_results[]` | repeated `int32` | With `separately_search_in_each_object_type`, the object type IDs whose results were cut by `limit`. Otherwise empty. |
| `search_execution_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Timing information for diagnostics. |
| `search_execution_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_execution_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_execution_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_execution_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
| `options` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Search status flags, for example `resorted_to_default_sort` when the requested sorting was replaced by relevance order. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `options.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `options.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `options.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `options.resorted_to_default_sort_too_many_results` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
| `options.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |
## Related methods
- [IRPCObjectOperations.GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md): Gets the version information and the property values of several objects in one call. The preferred way to read objects.
---
# IRPCSearch.GetObjectCountInSearch
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Counts the objects that match the given conditions without returning them.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetObjectCountInSearch`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-count-in-search`
- **Request:** [`GetObjectCountInSearchRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/index.md#request)
- **Response:** [`GetObjectCountInSearchResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Takes the same conditions as [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md) and counts
the same objects: latest versions the caller can see, deleted objects included unless excluded by a
condition. The result is one count for all object types together. The count stops at 10,000 by
default (a vault setting); a larger count is reported with `SRCOUNTFLAGS.more_than`. No search
timeout is applied.
## Request: GetObjectCountInSearchRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callimp` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `search_options` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | The search index and search mode. Leave unset for the vault's default index. |
| `search_options.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `search_options.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `search_options.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `search_options.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `search_condition_arrays[]` | repeated [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | Exactly one condition array; all of its conditions must match. No array or more than one array fails with "The parameter is incorrect." |
| `search_condition_arrays[].value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `search_condition_arrays[].value[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `search_condition_arrays[].value[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `search_condition_arrays[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `searchflags` | [`SearchFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md) | Search flags. `look_in_all_versions` and `return_latest_visible_version` are not supported and fail with "Invalid search condition." |
| `searchflags.all` | `bool` | All flags set, including any future flags. Do not use in searches. |
| `searchflags.look_in_all_versions` | `bool` | Also match older versions; each object is returned once. Cannot be combined with `sorting`, and `GetObjectCountInSearch` rejects it. |
| `searchflags.return_latest_visible_version` | `bool` | Return the latest visible version for each matching document. |
| `searchflags.separately_search_in_each_object_type` | `bool` | Search each object type separately and merge the results. The `limit` then applies to each object type, and `pages_with_more_results` lists the object types whose results were cut. |
| `searchflags.allow_quick_refresh_for_external_object_types` | `bool` | If a search with an external ID condition on an external object type finds nothing, refresh the object type from its external database and search again. |
| `searchflags.disable_relevancy_ranking` | `bool` | Do not rank the results by relevance. |
| `searchflags.separately_search_specific_object_types` | `bool` | Allows only specified object types to be searched separately. |
| `searchflags.include_unmanaged_objects` | `bool` | Extends the search to include unmanaged objects. |
| `searchflags.individual_limit_for_each_external_repository` | `bool` | Ensures that up to the specified maximum number of results are returned from each repository. |
## Response: GetObjectCountInSearchResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `psrcountarr[]` | repeated [`SearchResultsCount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsCount/index.md) | One count, with `group_id` -100 (all object types). `flags.exact_measure` means `count` is exact; `flags.more_than` means more objects match than `count`. |
| `psrcountarr[].group_id` | `int32` | The group that was counted: an object type ID, or -100 for all object types. |
| `psrcountarr[].flags` | [`SRCOUNTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRCOUNTFLAGS/index.md) | How to read `count`: `exact_measure` if exact, `more_than` if more objects match. |
| `psrcountarr[].flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `psrcountarr[].flags.exact_measure` | `bool` | If available, the reported result count is an exact measure. |
| `psrcountarr[].flags.more_than` | `bool` | If available, the reported result count is not an exact measure but it indicates that an exact count is more than the reported count. |
| `psrcountarr[].flags.multi_phase_initial` | `bool` | If available, the reported result count is based on the added items only. |
| `psrcountarr[].flags.multi_phase_count_only` | `bool` | If available, the reported result count is to be associated with a group without actual results. |
| `psrcountarr[].flags.multi_phase` | `bool` | If available, the reported result count supports multi-phase search, and it is to be associated with the initial result count rather than the total count. |
| `psrcountarr[].flags.additional_items` | `bool` | Identifies a search results count. |
| `psrcountarr[].count` | `uint32` | The number of matching objects. |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
## Related methods
- [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md): Searches the vault for objects that match the given conditions.
---
# IRPCSearch.GetFacetValues
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Retrieves the facet values for the documents that satisfy the specified search conditions.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetFacetValues`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-facet-values`
- **Request:** [`GetFacetValuesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/index.md#request)
- **Response:** [`GetFacetValuesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
For search UIs that show facets (refiners) next to full-text search results. Facets are computed
only when the vault's search index supports them (not with a dtSearch index) and the search has
exactly one full-text (any-field) condition. Otherwise the call succeeds with empty `data`. The
`data` string uses an
internal format that the M-Files clients read; it is not described here.
## Request: GetFacetValuesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `search_options` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | Search options. |
| `search_options.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `search_options.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `search_options.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `search_options.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `search_condition_arrays[]` | repeated [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | Exactly one condition array; all of its conditions must match. No array or more than one array fails with "Invalid search condition." |
| `search_condition_arrays[].value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `search_condition_arrays[].value[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `search_condition_arrays[].value[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `search_condition_arrays[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `facets_requested[]` | repeated [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The facets to compute, as expressions; for example an `EXPRESSION_TYPE_PROPERTY_VALUE` expression for property 100 (Class). |
| `facets_requested[].type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `facets_requested[].data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `facets_requested[].data.property_value` | [`ExpressionUnion.PropertyValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-PropertyValueData) (oneof data) | Expression for property values. |
| `facets_requested[].data.id_segment` | [`ExpressionUnion.IdSegmentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-IdSegmentData) (oneof data) | Expression for document ID segments. |
| `facets_requested[].data.status_value` | [`ExpressionUnion.StatusValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-StatusValueData) (oneof data) | Expression for status values such as Document ID or CheckedOutToUser. |
| `facets_requested[].data.file_value` | [`ExpressionUnion.FileValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-FileValueData) (oneof data) | Expression for file values such as file size. |
| `facets_requested[].data.typed_value` | [`ExpressionUnion.TypedValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-TypedValueData) (oneof data) | Expression for values of specific data type. Lookup-typed values also specify the value list. |
| `facets_requested[].data.any_field` | [`ExpressionUnion.AnyFieldData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-AnyFieldData) (oneof data) | Expression for values of any field (any property, file name etc.). |
| `facets_requested[].data.permissions` | [`ExpressionUnion.PermissionsData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-PermissionsData) (oneof data) | Expression for permissions (ACL). |
| `facets_requested[].indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `facets_requested[].indirection_levels[].type` | `bool` | True if `id` is a property definition ID; false if it is an object type ID. An object type level follows a reference to an object of that type through any property. |
| `facets_requested[].indirection_levels[].id` | `int32` | The property definition ID or object type ID to follow. |
| `max_facet_values_count` | `uint32` | The maximum number of facet values returned for each facet. Use 0 to retrieve all facet values. |
| `facetsearchflags` | [`FACETSEARCHFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FACETSEARCHFLAGS/index.md) | Facet search flags. Ignored if bFacetMode is false. |
| `facetsearchflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `facetsearchflags.enabled` | `bool` | Facet search is enabled. |
| `facetsearchflags.ignore_search_permissions` | `bool` | No ACL check on facet search. |
| `facetsearchflags.ignore_group_permissions` | `bool` | No ACL check on facet groups. |
| `facetsearchflags.ignore_value_permissions` | `bool` | No ACL check on individual facet values. |
| `facetsearchflags.sort_facets` | `bool` | Sort facet values in descending occurrence order within each facet group. |
| `facetsearchflags.ascending_order` | `bool` | If SortFacetValues is present, sort facet values in ascending occurrence order within each facet group. |
| `facet_filter` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | If set, specifies the additional facet search filter. |
| `facet_filter.value` | `string` | String. |
## Response: GetFacetValuesResponse
> Nested 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` | `string` | Receives the facet values as string data. Use CData_FacetValues to inspect the data. |
| `psearchstatusflags` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Receives search status flags. |
| `psearchstatusflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `psearchstatusflags.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `psearchstatusflags.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `psearchstatusflags.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `psearchstatusflags.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `psearchstatusflags.resorted_to_default_sort_too_many_results` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
| `psearchstatusflags.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
---
# IRPCSearch.GetFolderContents
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Lists the contents of a view or a view level: subviews, grouping folders and objects.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetFolderContents`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-contents`
- **Request:** [`GetFolderContentsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md#request)
- **Response:** [`GetFolderContentsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
This is how the M-Files clients browse views. `path` is the folder location from the vault root:
1. An empty `path` lists the root: `view_folders` holds the views the caller can see.
2. Append a `FOLDER_TYPE_VIEW_FOLDER` folder with a view ID to list that view. A view can contain
subviews (`view_folders`), grouping levels (`property_folders`), objects, or a mix. A view
nested in another view can also be listed without its parent view in `path`.
3. To open a grouping folder, append a `FOLDER_TYPE_PROPERTY_FOLDER` folder whose `typed_value` is
the [TypedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) returned in `property_folders`, unchanged.
Results are filtered by the caller's permissions. To find objects by conditions, use
[SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md) instead.
## Request: GetFolderContentsRequest
A request structure for GetFolderContents RPC call. It contains all request data.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically CALL_IMPORTANCE_NORMAL. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `target` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | Search options. |
| `target.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `target.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `target.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `target.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `path[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The folder location from the vault root, one [Folder](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) per level. Empty lists the vault root. |
| `path[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `path[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `path[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `path[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `path[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `path[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `path[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `path[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `page_requests[]` | repeated [`SearchResultsPageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsPageRequest/index.md) | If not empty, specifies search results page requests. |
| `page_requests[].object_type` | `int32` | The identifier of a search results group. |
| `page_requests[].page` | `int32` | The zero-based index of a page. |
| `page_requests[].options` | [`SRPREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRPREQUESTFLAGS/index.md) | Search results page request flags. |
| `page_requests[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `page_requests[].options.unseen_page` | `bool` | If available, the page request is for an unseen page. |
| `page_requests[].options.ignore_original_conditions` | `bool` | If available, the original conditions are ignored. This can be used when including ObjIDs. Do not use with SRPREQUEST_UNSEENPAGE. |
| `page_requests[].options.seen_page` | `bool` | If available, the page request is for an already seen page. |
| `page_requests[].options.initial_page` | `bool` | If available, the page request is initial and for an unseen page. Do not use with SRPREQUEST_SEENPAGE. |
| `page_requests[].seen_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | An array of ObjIDs. If the SRPREQUEST_UNSEENPAGE flag is available, these are ObjIDs to exclude. If the SRPREQUEST_SEENPAGE flag is available, these are ObjIDs to include. |
| `page_requests[].seen_objects[].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). |
| `page_requests[].seen_objects[].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`. |
| `limit` | `uint32` | The maximum number of objects to return; 0 leaves the limit to the server. `has_more_objects` tells whether more objects exist. |
| `facet_filter` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | If set, specifies the additional facet search filter. |
| `facet_filter.value` | `string` | String. |
| `sorting` | [`SearchResultsSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsSorting/index.md) | If not empty, specifies how search results are being sorted. |
| `sorting.rules` | [`SortRuleValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRuleValueArray/index.md) | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
| `sorting.rules.values[]` | repeated [`SortRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRule/index.md) | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
| `sorting.options` | [`SortFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortFlags/index.md) | Sort flags. Set `allow_resorting_to_default_sort` to get relevance order instead of an error when the rule cannot be applied. |
| `sorting.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `sorting.options.allow_resorting_to_default_sort` | `bool` | Allows resorting to default sorting if the specified sorting is not supported. If this flag is not present, an unsupported sort request causes an error. |
| `include_selected_folders` | `bool` | True to also return the user's selected folders of the level in selectedPropertyFolders. Ignored when the folder selection is not available. If the selected folders cannot be listed, for example because the search times out, the whole call fails; retry without includeSelectedFolders. |
| `selected_folders_only` | `bool` | With includeSelectedFolders, true to skip the normal property folder listing. Ignored without includeSelectedFolders. |
## Response: GetFolderContentsResponse
A response structure for GetFolderContents RPC call. It contains all response data.
> 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 |
|---|---|---|
| `view_folders[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | Resulting views array. |
| `view_folders[].id` | `int32` | The ID of the view. |
| `view_folders[].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). |
| `view_folders[].name` | `string` | The name of the view. |
| `view_folders[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `view_folders[].is_visible` | `bool` | Tells if the view is visible. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].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). |
| `view_folders[].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. |
| `view_folders[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].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. |
| `view_folders[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `view_folders[].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. |
| `view_folders[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `view_folders[].options.indexed` | `bool` | Materialized/indexed view. |
| `view_folders[].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. |
| `view_folders[].options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `view_folders[].guid` | `string` | GUID for the view. |
| `view_folders[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `view_folders[].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. |
| `property_folders[]` | repeated [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | Resulting property folders array. |
| `property_folders[].is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property_folders[].type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property_folders[].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. |
| `property_folders[].data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `property_folders[].data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `property_folders[].data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `property_folders[].data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `property_folders[].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. |
| `property_folders[].data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `property_folders[].data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `property_folders[].data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `property_folders[].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. |
| `property_folders[].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. |
| `property_folders[].data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `property_folders[].data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `property_folders[].data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `property_folders[].data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
| `traditional_folders[]` | repeated [`Lookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Lookup/index.md) | Resulting traditional folders array. |
| `traditional_folders[].value_list_item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The selected item. Only `obj_id` is needed when setting a value. |
| `traditional_folders[].value_list_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. |
| `traditional_folders[].value_list_item_info.name` | `string` | The name of the item. |
| `traditional_folders[].value_list_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). |
| `traditional_folders[].value_list_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. |
| `traditional_folders[].value_list_item_info.guid` | `string` | GUID for the item. |
| `traditional_folders[].value_list_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). |
| `traditional_folders[].value_list_item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `traditional_folders[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version of the selected object. The server returns `OBJ_VER_VERSION_TYPE_LATEST` (-1), meaning the latest version. |
| `traditional_folders[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `traditional_folders[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `traditional_folders[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `traditional_folders[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `objects[]` | repeated [`SearchResultsItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsItem/index.md) | Resulting objects array. |
| `objects[].object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
| `objects[].object.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `objects[].object.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `objects[].score` | `int32` | The relevance score of the result. Higher is more relevant. |
| `objects[].chunk` | `string` | For an Aino search, the passage of text that matched. Empty for other searches. |
| `external_repository_folders[]` | repeated [`ExternalView`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalView/index.md) | Reulsting external views array. |
| `external_repository_folders[].id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The view ID in external repository. |
| `external_repository_folders[].id.connection` | `string` | The external repository connection identifier. |
| `external_repository_folders[].id.item` | `string` | External ID within the scope of the connection to external system. |
| `external_repository_folders[].display_name` | `string` | The name of the view. |
| `external_repository_folders[].external_repository_icon_id` | `string` | The icon ID. |
| `external_repository_folders[].parent_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The view's parent ID in external repository. May be uninitialized if the external view does not have a parent. |
| `external_repository_folders[].parent_id.connection` | `string` | The external repository connection identifier. |
| `external_repository_folders[].parent_id.item` | `string` | External ID within the scope of the connection to external system. |
| `external_repository_folders[].object_data` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | If not null, the object representation of the folder. |
| `external_repository_folders[].object_data.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `external_repository_folders[].object_data.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `external_repository_folders[].object_data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `external_repository_folders[].object_data.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `external_repository_folders[].folder_capabilities` | [`FOLDERCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERCAPABILITYFLAGS/index.md) | Bit flags that provide information on the folder capabilities. |
| `external_repository_folders[].folder_capabilities.all` | `bool` | Specifies all flags set; Including any future flags. |
| `external_repository_folders[].folder_capabilities.can_search_within_this_folder` | `bool` | |
| `external_repository_folders[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `external_repository_folders[].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. |
| `external_repository_folders[].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. |
| `external_repository_folders[].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. |
| `external_repository_folders[].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. |
| `external_repository_folders[].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. |
| `external_repository_folders[].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. |
| `has_more_property_folders` | `bool` | Are there more property folders? |
| `has_more_objects` | `bool` | Are there more objects? |
| `has_more_external_repository_folders` | `bool` | Are there more external view folders? |
| `pages_with_more_results[]` | repeated `int32` | The list of item group identifications IDs the results of which were limited. The group identification ID depends on how the search results were grouped. E.g. object type ID. |
| `search_execution_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_execution_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_execution_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_execution_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_execution_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
| `options` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Search status flags. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `options.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `options.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `options.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `options.resorted_to_default_sort_too_many_results` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
| `options.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |
| `objects_continuation_token` | `string` | Continuation token for paginating search results for objects from Master Storage. |
| `has_additional_results` | `bool` | True if there are additional results that can't be counted in advance. |
| `selected_property_folders[]` | repeated [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The user's still valid selected property folders of the level, in no particular order. Filled only when includeSelectedFolders was requested. |
| `selected_property_folders[].is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `selected_property_folders[].type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `selected_property_folders[].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. |
| `selected_property_folders[].data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `selected_property_folders[].data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `selected_property_folders[].data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `selected_property_folders[].data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `selected_property_folders[].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. |
| `selected_property_folders[].data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `selected_property_folders[].data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `selected_property_folders[].data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `selected_property_folders[].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. |
| `selected_property_folders[].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. |
| `selected_property_folders[].data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `selected_property_folders[].data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `selected_property_folders[].data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `selected_property_folders[].data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
| `max_property_folders_limit` | `uint32` | The effective limit of the property folders of the level, which is also the folder selection limit. Zero means no limit, or that the folder selection is not available or the folder does not list a view level. Use canHaveSelectedFolders to tell if the level can hold a selection. |
| `can_have_selected_folders` | `bool` | True when the folders of the level can be selected. |
## Related methods
- [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md): Searches the vault for objects that match the given conditions.
- [GetFolderContentsOfPinboard](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOfPinboard/index.md): Gets the contents of the Pinboard items.
- [GetFolderContentsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOrDelta/index.md): Gets the contents of the specified folder, or a delta that indicates changes to document vault data since the logical timestamp known by the caller.
---
# IRPCSearch.CreateSummarization
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/CreateSummarization/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Creates an Aino summary for the M-Files clients.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/CreateSummarization`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-summarization`
- **Request:** [`CreateSummarizationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/CreateSummarization/index.md#request)
- **Response:** [`CreateSummarizationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/CreateSummarization/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The request and response are text documents in a format internal to the M-Files clients. The call
fails with "Your current subscription does not include the specified feature." when Aino
summarization is not available for the vault.
## Request: CreateSummarizationRequest
CreateSummarizationRequest method structure.
> Nested 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` | `string` | The request in JSON. |
## Response: CreateSummarizationResponse
CreateSummarizationResponse method structure.
> Nested 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` | `string` | The response in JSON. |
---
# IRPCSearch.GetFolderContentsOfPinboard
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOfPinboard/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the contents of the Pinboard items.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetFolderContentsOfPinboard`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-contents-of-pinboard`
- **Request:** [`GetFolderContentsOfPinboardRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOfPinboard/index.md#request)
- **Response:** [`GetFolderContentsOfPinboardResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOfPinboard/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by the M-Files clients to show the caller's pinned items.
## Request: GetFolderContentsOfPinboardRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `max_results` | `uint32` | Requested max results. If this is 0, it should be ignored. |
| `include_parent` | `bool` | True if parent location of the property and traditional folders to be included in the result. |
## Response: GetFolderContentsOfPinboardResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `view_folders_with_parent_location[]` | repeated [`ViewWithParentLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewWithParentLocation/index.md) | Resulting views. |
| `view_folders_with_parent_location[].parent_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The location of the view folder. |
| `view_folders_with_parent_location[].parent_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `view_folders_with_parent_location[].parent_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `view_folders_with_parent_location[].value` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | Resulting the view. |
| `view_folders_with_parent_location[].value.id` | `int32` | The ID of the view. |
| `view_folders_with_parent_location[].value.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). |
| `view_folders_with_parent_location[].value.name` | `string` | The name of the view. |
| `view_folders_with_parent_location[].value.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `view_folders_with_parent_location[].value.is_visible` | `bool` | Tells if the view is visible. |
| `view_folders_with_parent_location[].value.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. |
| `view_folders_with_parent_location[].value.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. |
| `view_folders_with_parent_location[].value.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `view_folders_with_parent_location[].value.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `view_folders_with_parent_location[].value.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. |
| `view_folders_with_parent_location[].value.guid` | `string` | GUID for the view. |
| `view_folders_with_parent_location[].value.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `view_folders_with_parent_location[].pinned_item_id` | `string` | The pinned item id is the guid key referencing this item in pinboard. |
| `property_folders_with_parent_location[]` | repeated [`PropertyFolderWithParent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyFolderWithParent/index.md) | Resulting property folders. |
| `property_folders_with_parent_location[].parent_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The location of the parent folders. Field with fid( 2 ) is reserved for legacy reasons and must not be re-used. |
| `property_folders_with_parent_location[].parent_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `property_folders_with_parent_location[].parent_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `property_folders_with_parent_location[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value of the property. |
| `property_folders_with_parent_location[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property_folders_with_parent_location[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property_folders_with_parent_location[].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. |
| `property_folders_with_parent_location[].pinned_item_id` | `string` | The pinned item id is the guid key referencing this item in pinboard. |
| `property_folders_with_parent_location[].last_parent_view` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The last view and search conditions from the parent folder. |
| `property_folders_with_parent_location[].last_parent_view.id` | `int32` | The ID of the view. |
| `property_folders_with_parent_location[].last_parent_view.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). |
| `property_folders_with_parent_location[].last_parent_view.name` | `string` | The name of the view. |
| `property_folders_with_parent_location[].last_parent_view.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `property_folders_with_parent_location[].last_parent_view.is_visible` | `bool` | Tells if the view is visible. |
| `property_folders_with_parent_location[].last_parent_view.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. |
| `property_folders_with_parent_location[].last_parent_view.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. |
| `property_folders_with_parent_location[].last_parent_view.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `property_folders_with_parent_location[].last_parent_view.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `property_folders_with_parent_location[].last_parent_view.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. |
| `property_folders_with_parent_location[].last_parent_view.guid` | `string` | GUID for the view. |
| `property_folders_with_parent_location[].last_parent_view.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `traditional_folders_with_parent_location[]` | repeated [`TraditionalFolderWithParent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TraditionalFolderWithParent/index.md) | Resulting traditional folders. |
| `traditional_folders_with_parent_location[].parent_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The location of the traditional folder. |
| `traditional_folders_with_parent_location[].parent_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `traditional_folders_with_parent_location[].parent_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `traditional_folders_with_parent_location[].value` | [`Lookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Lookup/index.md) | Traditional folders. This contains inserted or updated traditional folders if this struct represents a delta, otherwise it contains just a "normal" array of traditional folders. |
| `traditional_folders_with_parent_location[].value.value_list_item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The selected item. Only `obj_id` is needed when setting a value. |
| `traditional_folders_with_parent_location[].value.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version of the selected object. The server returns `OBJ_VER_VERSION_TYPE_LATEST` (-1), meaning the latest version. |
| `traditional_folders_with_parent_location[].pinned_item_id` | `string` | The pinned item id is the guid key referencing this item in pinboard. |
| `objects[]` | repeated [`PinnedObject`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PinnedObject/index.md) | Resulting objects. |
| `objects[].search_results_item` | [`SearchResultsItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsItem/index.md) | The search result item. |
| `objects[].search_results_item.object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
| `objects[].search_results_item.score` | `int32` | The relevance score of the result. Higher is more relevant. |
| `objects[].search_results_item.chunk` | `string` | For an Aino search, the passage of text that matched. Empty for other searches. |
| `objects[].pinned_item_id` | `string` | The pinned item id is the guid key referencing this item in pinboard. |
| `external_folders_with_parent_location[]` | repeated [`ExternalViewWithParentLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalViewWithParentLocation/index.md) | External views. ( Represented by ExternalViewWithParentLocation struct 0 |
| `external_folders_with_parent_location[].parent_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The location of the External view. |
| `external_folders_with_parent_location[].parent_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `external_folders_with_parent_location[].parent_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `external_folders_with_parent_location[].value` | [`ExternalView`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalView/index.md) | Resulting the Exterrnal view. |
| `external_folders_with_parent_location[].value.id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The view ID in external repository. |
| `external_folders_with_parent_location[].value.display_name` | `string` | The name of the view. |
| `external_folders_with_parent_location[].value.external_repository_icon_id` | `string` | The icon ID. |
| `external_folders_with_parent_location[].value.parent_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The view's parent ID in external repository. May be uninitialized if the external view does not have a parent. |
| `external_folders_with_parent_location[].value.object_data` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | If not null, the object representation of the folder. |
| `external_folders_with_parent_location[].value.folder_capabilities` | [`FOLDERCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERCAPABILITYFLAGS/index.md) | Bit flags that provide information on the folder capabilities. |
| `external_folders_with_parent_location[].value.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `external_folders_with_parent_location[].pinned_item_id` | `string` | The pinned item id is the guid key referencing this item in pinboard. |
| `more_property_folders` | `bool` | Are there more property folders? Currently it is false. It will be implemented in future. |
| `more_objects` | `bool` | Are there more objects? Currently it is false. It will be implemented in future. |
| `more_external_folders` | `bool` | Are there more external view folders? Currently it is false. It will be implemented in future. |
| `limited_item_groups[]` | repeated `int32` | Receives the list of item group identifications IDs the results of which were limited. The group identification ID depends on how the search results were grouped. E.g. object type ID.Currently it is not carrying any data. It will be implemented in future. |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation.Currently it is not carrying any data. It will be implemented in future. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
## Related methods
- [GetFolderContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md): Lists the contents of a view or a view level: subviews, grouping folders and objects.
---
# IRPCSearch.GetFolderContentsOrDelta
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOrDelta/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the contents of the specified folder, or a delta that indicates changes to document vault data since the logical timestamp known by the caller.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetFolderContentsOrDelta`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-contents-or-delta`
- **Request:** [`GetFolderContentsOrDeltaRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOrDelta/index.md#request)
- **Response:** [`GetFolderContentsOrDeltaResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContentsOrDelta/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by the M-Files clients to refresh a cached folder listing. For a plain listing, use
[GetFolderContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md).
## Request: GetFolderContentsOrDeltaRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callimp` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically CALL_IMPORTANCE_NORMAL. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `search_options` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | Search options. |
| `search_options.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `search_options.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `search_options.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `search_options.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `parent[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Describes the parent folder. |
| `parent[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `parent[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `parent[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `parent[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `parent[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `parent[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `parent[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `parent[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `results_page_requests[]` | repeated [`SearchResultsPageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsPageRequest/index.md) | If not empty, specifies search results page requests. |
| `results_page_requests[].object_type` | `int32` | The identifier of a search results group. |
| `results_page_requests[].page` | `int32` | The zero-based index of a page. |
| `results_page_requests[].options` | [`SRPREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRPREQUESTFLAGS/index.md) | Search results page request flags. |
| `results_page_requests[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `results_page_requests[].options.unseen_page` | `bool` | If available, the page request is for an unseen page. |
| `results_page_requests[].options.ignore_original_conditions` | `bool` | If available, the original conditions are ignored. This can be used when including ObjIDs. Do not use with SRPREQUEST_UNSEENPAGE. |
| `results_page_requests[].options.seen_page` | `bool` | If available, the page request is for an already seen page. |
| `results_page_requests[].options.initial_page` | `bool` | If available, the page request is initial and for an unseen page. Do not use with SRPREQUEST_SEENPAGE. |
| `results_page_requests[].seen_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | An array of ObjIDs. If the SRPREQUEST_UNSEENPAGE flag is available, these are ObjIDs to exclude. If the SRPREQUEST_SEENPAGE flag is available, these are ObjIDs to include. |
| `results_page_requests[].seen_objects[].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). |
| `results_page_requests[].seen_objects[].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`. |
| `callers_current_vcversion` | `int64` | The vault content version ID currently known by the caller. If the vault content has not been updated since, *pi64CurrentVCVersionOnServer is set to this same number and no data is returned. Specify zero to force the retrieval of normal folder contents. When this is zero, the server never returns an appropriate delta. |
| `allow_returning_delta` | `bool` | True if the caller allows returning a delta (changes to the vault content). |
| `upper_change_limit_for_delta` | `uint32` | Specifies an upper change limit for returning a delta. If changes are no more than this limit, a delta can be returned. |
| `max_results` | `uint32` | Requested max results. If this is 0, it should be ignored. |
| `facet_filter` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | If set, specifies the additional facet search filter. |
| `facet_filter.value` | `string` | String. |
| `sorting` | [`SearchResultsSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsSorting/index.md) | If not empty, specifies how search results are being sorted. |
| `sorting.rules` | [`SortRuleValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRuleValueArray/index.md) | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
| `sorting.rules.values[]` | repeated [`SortRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRule/index.md) | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
| `sorting.options` | [`SortFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortFlags/index.md) | Sort flags. Set `allow_resorting_to_default_sort` to get relevance order instead of an error when the rule cannot be applied. |
| `sorting.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `sorting.options.allow_resorting_to_default_sort` | `bool` | Allows resorting to default sorting if the specified sorting is not supported. If this flag is not present, an unsupported sort request causes an error. |
## Response: GetFolderContentsOrDeltaResponse
> 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 |
|---|---|---|
| `current_vcversion_on_server` | `int64` | Receives the current vault content version on the server. If this is the same as the one specified by the caller, no delta data is returned. However a full folder content can be returned to refresh the single folder. |
| `views_or_delta` | [`ViewsOrDelta`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewsOrDelta/index.md) | Views or delta. |
| `views_or_delta.type` | `bool` | True if this struct represents a delta (i.e. just the occurred changes to views). |
| `views_or_delta.removed_views[]` | repeated `int32` | Removed views. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
| `views_or_delta.views[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | Views. This contains inserted or updated views if this struct represents a delta, otherwise it contains just a "normal" array of views. |
| `views_or_delta.views[].id` | `int32` | The ID of the view. |
| `views_or_delta.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). |
| `views_or_delta.views[].name` | `string` | The name of the view. |
| `views_or_delta.views[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `views_or_delta.views[].is_visible` | `bool` | Tells if the view is visible. |
| `views_or_delta.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. |
| `views_or_delta.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. |
| `views_or_delta.views[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `views_or_delta.views[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `views_or_delta.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. |
| `views_or_delta.views[].guid` | `string` | GUID for the view. |
| `views_or_delta.views[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `property_folders_or_delta` | [`PropertyFoldersOrDelta`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyFoldersOrDelta/index.md) | Property folders or delta. |
| `property_folders_or_delta.type` | `bool` | True if this struct represents a delta (i.e. just the occurred changes to property folders). |
| `property_folders_or_delta.removed_folders[]` | repeated [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | Removed property folders. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
| `property_folders_or_delta.removed_folders[].is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property_folders_or_delta.removed_folders[].type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property_folders_or_delta.removed_folders[].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. |
| `property_folders_or_delta.folders[]` | repeated [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | Property folders. This contains inserted or updated property folders if this struct represents a delta, otherwise it contains just a "normal" array of property folders. |
| `property_folders_or_delta.folders[].is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property_folders_or_delta.folders[].type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property_folders_or_delta.folders[].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. |
| `traditional_folders_or_delta` | [`TraditionalFoldersOrDelta`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TraditionalFoldersOrDelta/index.md) | Traditional folders or delta. |
| `traditional_folders_or_delta.type` | `bool` | True if this struct represents a delta (i.e. just the occurred changes to traditional folders). |
| `traditional_folders_or_delta.removed_folders[]` | repeated `int32` | Removed traditional folders. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
| `traditional_folders_or_delta.folders[]` | repeated [`Lookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Lookup/index.md) | Traditional folders. This contains inserted or updated traditional folders if this struct represents a delta, otherwise it contains just a "normal" array of traditional folders. |
| `traditional_folders_or_delta.folders[].value_list_item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The selected item. Only `obj_id` is needed when setting a value. |
| `traditional_folders_or_delta.folders[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version of the selected object. The server returns `OBJ_VER_VERSION_TYPE_LATEST` (-1), meaning the latest version. |
| `objects_or_delta` | [`ObjectsOrDelta`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectsOrDelta/index.md) | Objects or delta. |
| `objects_or_delta.type` | `bool` | True if this struct represents a delta (i.e. just the occurred changes to objects). |
| `objects_or_delta.removed_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Removed objects. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
| `objects_or_delta.removed_objects[].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). |
| `objects_or_delta.removed_objects[].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`. |
| `objects_or_delta.objects[]` | repeated [`SearchResultsItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsItem/index.md) | Objects. This contains inserted or updated objects if this struct represents a delta, otherwise it contains just a "normal" array of objects. |
| `objects_or_delta.objects[].object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
| `objects_or_delta.objects[].score` | `int32` | The relevance score of the result. Higher is more relevant. |
| `objects_or_delta.objects[].chunk` | `string` | For an Aino search, the passage of text that matched. Empty for other searches. |
| `objects_or_delta.object_property_values[]` | repeated [`PropertyValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueArray/index.md) | Objects' property values. |
| `objects_or_delta.object_property_values[].value[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values. |
| `objects_or_delta.object_acls[]` | repeated [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If not empty, objects' ACLs. |
| `objects_or_delta.object_acls[].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. |
| `objects_or_delta.object_acls[].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. |
| `objects_or_delta.object_acls[].custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `objects_or_delta.object_acls[].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. |
| `objects_or_delta.object_acls[].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. |
| `objects_or_delta.object_acls[].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. |
| `objects_or_delta.limited_item_groups[]` | repeated `int32` | Receives the list of item group identifications ids those results were limited. The group identification id depends on how the search results were grouped. E.g. object type id. |
| `objects_or_delta.continuation_token` | `string` | Continuation token for paginating search results from Master Storage. |
| `objects_or_delta.has_additional_results` | `bool` | True if there are additional results that can't be counted in advance. |
| `vl_items_delta` | [`ValueListItemsDelta`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemsDelta/index.md) | Value list items delta. Valid only if a delta is returned for objects. |
| `vl_items_delta.changed_value_lists[]` | repeated `int32` | Changed value lists. |
| `json_external_view_folders_or_delta[]` | repeated [`ExternalView`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalView/index.md) | External views or delta. |
| `json_external_view_folders_or_delta[].id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The view ID in external repository. |
| `json_external_view_folders_or_delta[].id.connection` | `string` | The external repository connection identifier. |
| `json_external_view_folders_or_delta[].id.item` | `string` | External ID within the scope of the connection to external system. |
| `json_external_view_folders_or_delta[].display_name` | `string` | The name of the view. |
| `json_external_view_folders_or_delta[].external_repository_icon_id` | `string` | The icon ID. |
| `json_external_view_folders_or_delta[].parent_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The view's parent ID in external repository. May be uninitialized if the external view does not have a parent. |
| `json_external_view_folders_or_delta[].parent_id.connection` | `string` | The external repository connection identifier. |
| `json_external_view_folders_or_delta[].parent_id.item` | `string` | External ID within the scope of the connection to external system. |
| `json_external_view_folders_or_delta[].object_data` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | If not null, the object representation of the folder. |
| `json_external_view_folders_or_delta[].object_data.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `json_external_view_folders_or_delta[].object_data.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `json_external_view_folders_or_delta[].object_data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `json_external_view_folders_or_delta[].object_data.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `json_external_view_folders_or_delta[].folder_capabilities` | [`FOLDERCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERCAPABILITYFLAGS/index.md) | Bit flags that provide information on the folder capabilities. |
| `json_external_view_folders_or_delta[].folder_capabilities.all` | `bool` | Specifies all flags set; Including any future flags. |
| `json_external_view_folders_or_delta[].folder_capabilities.can_search_within_this_folder` | `bool` | |
| `json_external_view_folders_or_delta[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `json_external_view_folders_or_delta[].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_external_view_folders_or_delta[].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_external_view_folders_or_delta[].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_external_view_folders_or_delta[].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_external_view_folders_or_delta[].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_external_view_folders_or_delta[].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. |
| `more_property_folders` | `bool` | Are there more property folders? |
| `max_property_folders_limit` | `uint32` | The maximum property folders allowed. The server used this value to limit the returned property folders. If zero, the limit is infinite. |
| `more_objects` | `bool` | Are there more objects? |
| `max_objects_limit` | `uint32` | The maximum objects allowed. The server used this value to limit the returned objects. If zero, the limit is infinite. |
| `more_external_view_folders` | `bool` | Are there more external views? |
| `max_external_view_folders_limit` | `uint32` | The maximum external views allowed. The server used this value to limit the returned objects. If zero, the limit is infinite. |
| `psearchstatusflags` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Receives search status flags. |
| `psearchstatusflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `psearchstatusflags.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `psearchstatusflags.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `psearchstatusflags.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `psearchstatusflags.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `psearchstatusflags.resorted_to_default_sort_too_many_results` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
| `psearchstatusflags.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
## Related methods
- [GetFolderContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderContents/index.md): Lists the contents of a view or a view level: subviews, grouping folders and objects.
---
# IRPCSearch.GetFolderObjectsCount
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderObjectsCount/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the count of objects in the specified folder.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetFolderObjectsCount`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-objects-count`
- **Request:** [`GetFolderObjectsCountRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderObjectsCount/index.md#request)
- **Response:** [`GetFolderObjectsCountResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFolderObjectsCount/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by the M-Files clients to show object counts in folder listings. To count the results of a
search, use [GetObjectCountInSearch](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/index.md).
## Request: GetFolderObjectsCountRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callimp` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically CALL_IMPORTANCE_NORMAL. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `search_options` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | Search options. |
| `search_options.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `search_options.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `search_options.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `search_options.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `parent[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Describes the parent folder. |
| `parent[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `parent[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `parent[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `parent[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `parent[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `parent[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `parent[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `parent[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `facetsearchflags` | [`FACETSEARCHFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FACETSEARCHFLAGS/index.md) | Facet search flags. Ignored if bFacetMode is false. |
| `facetsearchflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `facetsearchflags.enabled` | `bool` | Facet search is enabled. |
| `facetsearchflags.ignore_search_permissions` | `bool` | No ACL check on facet search. |
| `facetsearchflags.ignore_group_permissions` | `bool` | No ACL check on facet groups. |
| `facetsearchflags.ignore_value_permissions` | `bool` | No ACL check on individual facet values. |
| `facetsearchflags.sort_facets` | `bool` | Sort facet values in descending occurrence order within each facet group. |
| `facetsearchflags.ascending_order` | `bool` | If SortFacetValues is present, sort facet values in ascending occurrence order within each facet group. |
| `srcrequestarr[]` | repeated [`SearchResultsCountRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsCountRequest/index.md) | Search results count requests. |
| `srcrequestarr[].group_id` | `int32` | The identifier of a search results group. |
| `srcrequestarr[].count_threshold` | `uint32` | Threshold for the count. If zero, it should be ignored. A non-zero value specifies that the caller does not request an exact count if it is greater than this threshold value. If a real count is smaller than or equal this threshold, it is reported as an exact count. |
| `max_objects_limit_for_groups` | `uint32` | The OT specific limit for object count. |
| `facet_filter` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | If set, specifies the additional facet search filter. |
| `facet_filter.value` | `string` | String. |
## Response: GetFolderObjectsCountResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `psrcountarr[]` | repeated [`SearchResultsCount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsCount/index.md) | Resulting search results counts. |
| `psrcountarr[].group_id` | `int32` | The group that was counted: an object type ID, or -100 for all object types. |
| `psrcountarr[].flags` | [`SRCOUNTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRCOUNTFLAGS/index.md) | How to read `count`: `exact_measure` if exact, `more_than` if more objects match. |
| `psrcountarr[].flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `psrcountarr[].flags.exact_measure` | `bool` | If available, the reported result count is an exact measure. |
| `psrcountarr[].flags.more_than` | `bool` | If available, the reported result count is not an exact measure but it indicates that an exact count is more than the reported count. |
| `psrcountarr[].flags.multi_phase_initial` | `bool` | If available, the reported result count is based on the added items only. |
| `psrcountarr[].flags.multi_phase_count_only` | `bool` | If available, the reported result count is to be associated with a group without actual results. |
| `psrcountarr[].flags.multi_phase` | `bool` | If available, the reported result count supports multi-phase search, and it is to be associated with the initial result count rather than the total count. |
| `psrcountarr[].flags.additional_items` | `bool` | Identifies a search results count. |
| `psrcountarr[].count` | `uint32` | The number of matching objects. |
| `psearchstatusflags` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Receives search status flags. |
| `psearchstatusflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `psearchstatusflags.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `psearchstatusflags.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `psearchstatusflags.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `psearchstatusflags.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `psearchstatusflags.resorted_to_default_sort_too_many_results` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
| `psearchstatusflags.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
## Related methods
- [GetObjectCountInSearch](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectCountInSearch/index.md): Counts the objects that match the given conditions without returning them.
---
# IRPCSearch.GetObjectsCountForNotifications
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectsCountForNotifications/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the objects count for notification badge.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetObjectsCountForNotifications`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-objects-count-for-notifications`
- **Request:** [`GetObjectsCountForNotificationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectsCountForNotifications/index.md#request)
- **Response:** [`GetObjectsCountForNotificationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetObjectsCountForNotifications/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by the M-Files clients for notification badges: the counts of the caller's "Assigned to Me"
and "Checked Out to Me" views.
## Request: GetObjectsCountForNotificationsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `notification_data_request_flags` | [`NOTIFICATIONDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NOTIFICATIONDATAREQUESTFLAGS/index.md) | Notification data request flags. |
| `notification_data_request_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `notification_data_request_flags.checked_out_to_me_on_this_computer` | `bool` | To get number of checked out objects from current user and current computer. |
| `notification_data_request_flags.checked_out_to_me` | `bool` | To get number of checked out objects by current user. |
| `notification_data_request_flags.assigned_to_me` | `bool` | To get number of assigned objects to current user. |
| `search_flags` | [`SearchFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md) | Search flags. Supports 'INCLUDE_UNMANAGED_OBJECTS' flag only. |
| `search_flags.all` | `bool` | All flags set, including any future flags. Do not use in searches. |
| `search_flags.look_in_all_versions` | `bool` | Also match older versions; each object is returned once. Cannot be combined with `sorting`, and `GetObjectCountInSearch` rejects it. |
| `search_flags.return_latest_visible_version` | `bool` | Return the latest visible version for each matching document. |
| `search_flags.separately_search_in_each_object_type` | `bool` | Search each object type separately and merge the results. The `limit` then applies to each object type, and `pages_with_more_results` lists the object types whose results were cut. |
| `search_flags.allow_quick_refresh_for_external_object_types` | `bool` | If a search with an external ID condition on an external object type finds nothing, refresh the object type from its external database and search again. |
| `search_flags.disable_relevancy_ranking` | `bool` | Do not rank the results by relevance. |
| `search_flags.separately_search_specific_object_types` | `bool` | Allows only specified object types to be searched separately. |
| `search_flags.include_unmanaged_objects` | `bool` | Extends the search to include unmanaged objects. |
| `search_flags.individual_limit_for_each_external_repository` | `bool` | Ensures that up to the specified maximum number of results are returned from each repository. |
## Response: GetObjectsCountForNotificationsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `assigned_to_me_objects_count` | `uint32` | Objects count from "Assigned to me" view. |
| `checked_out_to_me_objects_count_on_this_computer` | `uint32` | Number of checked out objects by current user from the current computer. |
| `checked_out_to_me_objects_count` | `uint32` | Objects count from "Checkedout to me" view. |
---
# IRPCSearch.GetPrefillProperties
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetPrefillProperties/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the property values that a new object created in the given folder gets from that folder.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetPrefillProperties`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-prefill-properties`
- **Request:** [`GetPrefillPropertiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetPrefillProperties/index.md#request)
- **Response:** [`GetPrefillPropertiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetPrefillProperties/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by the M-Files clients to prefill the metadata card when the user creates an object in a
view or grouping folder.
## Request: GetPrefillPropertiesRequest
> Nested 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` | Target object type. |
| `value[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Describes the parent folder. |
| `value[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `value[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `value[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `value[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `value[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `value[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `value[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `value[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
## Response: GetPrefillPropertiesResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `propertyvaluearray[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | List of prefill properties. |
| `propertyvaluearray[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `propertyvaluearray[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `propertyvaluearray[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `propertyvaluearray[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `propertyvaluearray[].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. |
---
# IRPCSearch.GetSearchHits
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetSearchHits/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Finds the words of a text that a full-text search condition matches, for hit highlighting.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetSearchHits`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-search-hits`
- **Request:** [`GetSearchHitsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetSearchHits/index.md#request)
- **Response:** [`GetSearchHitsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetSearchHits/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`search_condition` must be an `EXPRESSION_TYPE_ANY_FIELD` condition with `CONDITION_TYPE_CONTAINS`
and a text value; anything else fails with "The parameter is incorrect." The server always
matches any of the search words, also for an all-words or Boolean search. `hits` lists the matched
words as they appear in `input`, for example "invoices" for the search word "invoice".
## Request: GetSearchHitsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `search_options` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | Search options. |
| `search_options.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `search_options.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `search_options.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `search_options.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `input` | `string` | The source text for searching. |
| `search_condition` | [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The full-text search condition that specifies the search words (Represented by SearchCondition sturct). |
| `search_condition.expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `search_condition.expression.type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `search_condition.expression.data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `search_condition.expression.indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `search_condition.type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `search_condition.value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `search_condition.value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `search_condition.value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `search_condition.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. |
## Response: GetSearchHitsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `hits[]` | repeated `string` | Receives the hit strings. |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
---
# IRPCSearch.QuerySearchAgent
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/QuerySearchAgent/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Runs an Aino Search query for the M-Files clients.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/QuerySearchAgent`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/query-search-agent`
- **Request:** [`QuerySearchAgentRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/QuerySearchAgent/index.md#request)
- **Response:** [`QuerySearchAgentResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/QuerySearchAgent/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The request and response are text documents in a format internal to the M-Files clients. The call
requires Aino Search to be enabled on the server.
## Request: QuerySearchAgentRequest
QuerySearchAgentRequest method structure.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `query` | `string` | The query in JSON. |
## Response: QuerySearchAgentResponse
QuerySearchAgentResponse method structure.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `response` | `string` | The response in JSON. |
---
# IRPCSearch.SearchReferencedValueListItems
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchReferencedValueListItems/
Badges: `Vault API / core` `write` `session or assertion`
Gets value list items that are referenced by one or more documents (possibly limiting the set of documents with conditions) in ID order.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/SearchReferencedValueListItems`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-referenced-value-list-items`
- **Request:** [`SearchReferencedValueListItemsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchReferencedValueListItems/index.md#request)
- **Response:** [`SearchReferencedValueListItemsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchReferencedValueListItems/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Returns the items of `value_list` that at least one matching object refers to, in ascending ID
order, `batch_size` items at a time. For the next batch, pass the ID of the last item received
in `last_received_item_id`. Only the first condition array in `utf8szconds` is used.
## Request: SearchReferencedValueListItemsRequest
> Nested 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` | ID of the valuelist. |
| `last_received_item_id` | `uint32` | The last valuelist item id that was received by the client. 0 for first call. |
| `batch_size` | `uint32` | The maximum number of items to return. Set a value greater than 0: a request with 0 returns no items. |
| `utf8szconds[]` | repeated [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | The conditions that the referring objects must match. Only the first condition array is used; all of its conditions must match. |
| `utf8szconds[].value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `utf8szconds[].value[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `utf8szconds[].value[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `utf8szconds[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
## Response: SearchReferencedValueListItemsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pvlitems[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Resulting valuelist items. |
| `pvlitems[].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. |
| `pvlitems[].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. |
| `pvlitems[].item_info.name` | `string` | The name of the item. |
| `pvlitems[].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). |
| `pvlitems[].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. |
| `pvlitems[].item_info.guid` | `string` | GUID for the item. |
| `pvlitems[].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). |
| `pvlitems[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `pvlitems[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `pvlitems[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `pvlitems[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `pvlitems[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `pvlitems[].owner_name` | `string` | The name of the owner item. |
| `pvlitems[].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. |
| `pvlitems[].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. |
| `pvlitems[].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. |
| `pvlitems[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `pvlitems[].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. |
| `pvlitems[].icon.value` | `bytes` | Array of bytes. |
---
# IRPCSearch.SearchViewLevelFolders
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchViewLevelFolders/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
The search covers the folders that the listing of the level would show without the folder limit. The
results can be saved as part of the user's folder selection. Fails with E_NOTIMPL when the feature is
not enabled on the server.
- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/SearchViewLevelFolders`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-view-level-folders`
- **Request:** [`SearchViewLevelFoldersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchViewLevelFolders/index.md#request)
- **Response:** [`SearchViewLevelFoldersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchViewLevelFolders/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: SearchViewLevelFoldersRequest
Searches the folders of one view level by name. The search covers every folder that the listing of the level would
show without the folder limit, including the folders beyond it.
> Nested 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_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The folder location, from the vault root to the parent of the level whose folders are searched. The same path that the listing of the level uses. |
| `folder_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `folder_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `folder_location[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `folder_location[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `folder_location[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `folder_location[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `folder_location[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `folder_location[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `search_text` | `string` | The text that the folder names must contain, ignoring letter case. At most 100 characters. Empty matches every folder. |
| `limit` | `uint32` | The maximum number of results. Zero means 100. The value is clamped to 1-500. |
## Response: SearchViewLevelFoldersResponse
A structure that specifies the response type for the SearchViewLevelFolders 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 |
|---|---|---|
| `results[]` | repeated [`ViewLevelFolderSearchResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewLevelFolderSearchResult/index.md) | The matching folders, at most the requested limit, sorted by name ignoring case and diacritics, with numbers in numeric order. |
| `results[].folder` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The folder, in the same form as the property folders of the level's listing. It can be saved as part of a folder selection as it is. |
| `results[].folder.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `results[].folder.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `results[].folder.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. |
| `results[].is_selected` | `bool` | True when the folder is in the user's folder selection for the location. |
| `has_more_results` | `bool` | True when more folders match than were returned, or when the level has more folders than the search goes through. Narrowing the search text does not reveal the folders beyond that cap. |
---
# Objects, versions, properties and files (IRPCObjectOperations)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/
An interface for handling documents and files
Provides methods for adding, modifying and removing objects.
Includes version control operations as well, such as checkout and check-in.
- **gRPC service:** `MFiles.IRPCObjectOperations`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 132
- **Proto file:** [`mfiles/IRPCObjectOperations.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCObjectOperations.proto)
## Overview
Everything you do with individual objects: read their versions, properties and files, create
them, change them, and manage their lifecycle. To find objects in the first place, use
[SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md).
| Job | Method |
| --- | --- |
| Read the latest version and properties of one or many objects | [GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md) |
| Read one object, latest or a specific version | [GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md) |
| Read selected data (properties, ACL, permissions, relationships, comments) per object | [GetObjectDataOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectDataOfMultipleObjects/index.md) |
| Read the properties of a known, specific version | [GetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md) |
| Resolve the latest version number | [GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md) |
| List the versions of an object | [GetObjectHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/index.md) |
| Download a file | [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md), [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md) |
| Get the text of a file (plain text or Markdown) | [GetTextContentForFileWithFormat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md) |
| Upload content for a new object | [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md), [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) |
| Create an object, with or without files | [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md), [AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md) |
| Change properties | [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md), [SetPropertiesMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/index.md) |
| Check out, check in, undo a check-out | [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md), [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md), [UndoCheckout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md) |
| Add a file to an object | [AddObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md) |
| Workflow states and transitions | [GetWorkflowStates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStates/index.md), [GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md) |
| What the caller may do with an object | [GetEffectivePermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetEffectivePermissions/index.md) |
| Delete, undelete, destroy | [RemoveObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md), [UndeleteObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md), [DestroyObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md) |
The other methods are batch variants of the ones above (`...Multiple`), history and version
comments, duplicate detection (`Find...Duplicates`), objects from external repositories
(`...External...`, `...Promote...`, `...Unmanaged...`), and helpers for M-Files client features
such as document comparison and external editing.
**Versions.** Most read methods take an [ObjVer](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) and need a *specific*
version (`OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`). `GetProperties`,
`GetPropertiesOfMultipleObjects`, `GetObjectFiles`, `GetRelationshipsForObject` and
`GetLatestVersionCommentOfMultipleObjects` answer "Not found." to the `OBJ_VER_VERSION_TYPE_LATEST`
marker. To read the latest version, either use a method that has its own "latest" switch
(`GetObjectVersionAndPropertiesOfMultipleObjects`, `GetObjectInfoAndProperties`,
`GetObjectDataOfMultipleObjects`, `GetObjectInfo`), or resolve the number first with
`GetLatestObjectVersion`. The same applies to files: [FileVer](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) must name a
specific file version.
**Checked-out objects.** "Latest" means the latest checked-in version. A version that is
checked out is returned only to the user who has it checked out, and only where the request says
so (`allow_checked_out`, `OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_LATEST_VERSIONS`), except
`GetObjectInfo`, which always returns it to that user.
**Creating objects: always set `acl`.** `AddObjectWithFiles`, `AddObject` and the other creating
methods store the ACL you send; they do not compute one from the class. An unset `acl` gives the
new object an empty ACL: once it is checked in, only users with the vault-level right to see all
objects can see it, not even its creator. Send a named ACL, for example
`acl { custom_component { has_named_acl: true named_acl_id: -1 } }` ("Full control for all
internal users"); see [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md).
**Files.** The object's version information ([ObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md)
`files`) already lists its files with their `file_ver`, size and MD5 checksum, so after reading
an object you can download its files without calling `GetObjectFiles`. `DownloadFile`,
`DownloadFileWithDownloadID`, `DownloadFileWithDownloadKey`, `GetFileDownloadUrl` and
`GetFileDownloadUrl2` serve the HTTP gateway and answer "Not implemented." over native gRPC.
**Errors.** Errors arrive with gRPC status `UNKNOWN` and the M-Files error message as the status
details. A missing object or version is "Not found." (0x8004000B). An object the caller is not
allowed to read is "Access denied." (0x800407E4) for most methods, but "Not found." for
`GetObjectInfoAndProperties`, and `GetObjectHistory` returns an empty list for it.
Background:
[Objects and versions](https://developer.m-files.com/APIs/gRPC-API/concepts/objects-and-versions/index.md),
[Properties and values](https://developer.m-files.com/APIs/gRPC-API/concepts/properties-and-values/index.md),
[Permissions](https://developer.m-files.com/APIs/gRPC-API/concepts/permissions/index.md),
[Workflows](https://developer.m-files.com/APIs/gRPC-API/concepts/workflows/index.md) and
[Files](https://developer.m-files.com/APIs/gRPC-API/runtime/files/index.md).
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md) | Gets the version information and the property values of one object, either its latest version or a specific version. | `write` `session or assertion` `returns metadata structure version` |
| [GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md) | Gets the version information and the property values of several objects in one call. The preferred way to read objects. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectDataOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectDataOfMultipleObjects/index.md) | Gets selected data of several objects: version information, properties, ACL, the caller's permissions, relationships, version comments and more, with a result or an error per object. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md) | Gets the property values of one specific object version. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFiles/index.md) | Gets the files of a specific object version. | `write` `session or assertion` `returns metadata structure version` |
| [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md) | Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md) | Reads a block of a file from a download session. | `read` `session or assertion` `idempotent` |
| [DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md) | Closes a download session. | `read` `session or assertion` `idempotent` |
| [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) | Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object. | `write` `session or assertion` `idempotent` |
| [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) | Completes an upload made with UploadTempFile. | `write` `session or assertion` `idempotent` |
| [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) | Creates a new object, optionally with its files, and optionally checks it in. | `write` `session or assertion` `returns metadata structure version` |
| [AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md) | Creates a new object without files. | `write` `session or assertion` `returns metadata structure version` |
| [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md) | Checks out one object. | `write` `session or assertion` `returns metadata structure version` |
| [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md) | Checks in one object. | `write` `session or assertion` `returns metadata structure version` |
| [UndoCheckout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md) | Undoes the checkout of one object. | `write` `session or assertion` `returns metadata structure version` |
| [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md) | Adds, replaces or removes property values of an object. | `write` `session or assertion` `returns metadata structure version` |
| [SetPropertiesMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/index.md) | If the object is currently checked in, a new checked-in version is created. If the object is currently checked out, the changes are applied to the checked-out version. | `write` `session or assertion` `returns metadata structure version` |
| [AddObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md) | Adds new document file to a document. | `write` `session or assertion` `returns metadata structure version` |
| [GetObjectHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/index.md) | Lists the existing versions of an object, oldest first. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetWorkflowStates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStates/index.md) | Gets the states of the given workflow in the appropriate order. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md) | Gets the states and transitions of the given workflow. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetEffectivePermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetEffectivePermissions/index.md) | Gets the effective permissions of a document. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [RemoveObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md) | Removes one object i.e. marks it deleted. | `write` `session or assertion` `returns metadata structure version` |
| [UndeleteObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md) | Undeletes a previously removed object. | `write` `session or assertion` `returns metadata structure version` |
| [DestroyObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md) | Permanently destroys an object, or one version of it. | `write` `session or assertion` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [AddObjectWithFilesWithPropertyMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/index.md) | Creates a new object with files, storing metadata about each property value (who or what set it, why, and with what confidence). | `write` `session or assertion` `returns metadata structure version` |
| [AddOrUpdateExternalObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddOrUpdateExternalObject/index.md) | Creates, updates or deletes the object that mirrors an item of an external system, identified by its external ID. | `write` `session or assertion` |
| [AddSingleFileDocument_SingleStep](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep/index.md) | Creates a single-file document from inline file content and checks it in. Older form; prefer AddObjectWithFiles with an inline file source. | `write` `session or assertion` `returns metadata structure version` |
| [AddSingleFileDocument_SingleStep2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2/index.md) | Creates a single-file document from inline file content. Older form; prefer AddObjectWithFiles with an inline file source. | `write` `session or assertion` `returns metadata structure version` |
| [AddSingleFileDocument_SingleStep3](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3/index.md) | Creates a single-file document from inline file content and returns its file version. Older form; prefer AddObjectWithFiles with an inline file source. | `write` `session or assertion` `returns metadata structure version` |
| [AddStubObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddStubObject/index.md) | Creates a stub object that stands for an object in another vault. Used by replication and cross-vault relationships; not for applications. | `write` `session or assertion` `returns metadata structure version` |
| [AddVersionTag](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddVersionTag/index.md) | Adds the specified tag to the document version. If the tag already exists in the specified target version, this method does nothing. Other tags are not affected. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [ChangeSecurity](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ChangeSecurity/index.md) | Changes the security settings of an object. | `write` `session or assertion` `returns metadata structure version` |
| [CheckAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckAccess/index.md) | Checks user's access to an object based on an ACL. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [CheckInExternalChanges](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInExternalChanges/index.md) | Creates new versions of objects whose files were changed in an external editing system (SharePoint Embedded co-authoring). No version is created for an object without changes. | `write` `session or assertion` `returns metadata structure version` |
| [CheckInMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInMultiple/index.md) | Checks in several objects in one call. | `write` `session or assertion` `returns metadata structure version` |
| [CheckOutMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOutMultiple/index.md) | Checks out several objects in one call. | `write` `session or assertion` `returns metadata structure version` |
| [ConvertToPDF](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ConvertToPDF/index.md) | Converts the specified object file to PDF format. | `write` `session or assertion` `returns metadata structure version` |
| [CopyConflictObjectAsNewVersionToBaseObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CopyConflictObjectAsNewVersionToBaseObject/index.md) | Resolves a replication conflict by adding the conflict object's content as a new version of the base object. Used by M-Files clients; not for applications. | `write` `session or assertion` `returns metadata structure version` |
| [CountObjectVersionsMatchingConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions/index.md) | Counts the versions of an object that DestroyObjectVersionsByConditions would destroy with the same inputs, without destroying anything. | `write` `session or assertion` `returns metadata structure version` |
| [CreateNewObjectWithPropertyMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CreateNewObjectWithPropertyMetadata/index.md) | Creates a new object without files, storing metadata about each property value. | `write` `session or assertion` `returns metadata structure version` |
| [DemoteObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DemoteObjects/index.md) | Removes the M-Files metadata from promoted objects, turning them back into unmanaged objects of their external repository. | `write` `session or assertion` `returns metadata structure version` |
| [DestroyObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjects/index.md) | Permanently destroys several objects with all their versions. Requires the vault-level right to destroy objects. | `write` `session or assertion` `returns metadata structure version` |
| [DestroyObjectVersions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersions/index.md) | Permanently destroys specific object versions. | `write` `session or assertion` `returns metadata structure version` |
| [DestroyObjectVersionsByConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md) | Destroys the old versions of an object that match search conditions, and returns how many were destroyed. | `write` `session or assertion` `returns metadata structure version` |
| [DetectTextLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DetectTextLanguage/index.md) | Detects the language of a plain text. | `write` `session or assertion` `returns metadata structure version` |
| [DownloadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md) | Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway. | `write` `session or assertion` |
| [DownloadFileWithDownloadID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadID/index.md) | Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway. | `write` `session or assertion` |
| [DownloadFileWithDownloadKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadKey/index.md) | Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway. | `write` `session or assertion` |
| [DownloadTempFileFromUpload_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md) | Opens a download session for a committed upload, to read it back or as a PDF, without creating an object. | `read` `session or assertion` `idempotent` |
| [FindEmailDuplicates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindEmailDuplicates/index.md) | Finds duplicate email objects in the vault. | `write` `session or assertion` `returns metadata structure version` |
| [FindFileDuplicates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicates/index.md) | Finds files in the vault with the same content as the given file version. | `write` `session or assertion` `returns metadata structure version` |
| [FindFileDuplicatesOfObjVer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicatesOfObjVer/index.md) | Finds files in the vault with the same content as the files of the given object version. | `write` `session or assertion` `returns metadata structure version` |
| [FindFilesByChecksum](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFilesByChecksum/index.md) | Finds file versions in the vault by MD5 checksum. | `write` `session or assertion` `returns metadata structure version` |
| [FindVaultDuplicates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindVaultDuplicates/index.md) | Finds all groups of duplicate files in the vault. | `write` `session or assertion` `returns metadata structure version` |
| [FollowObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FollowObject/index.md) | Starts or stops following the specified object. While the object is being followed, the current user will be notified if the object changes. | `write` `session or assertion` `returns metadata structure version` |
| [GetAutomaticMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetAutomaticMetadata/index.md) | Gets automatic metadata from the vault's metadata providers, for an object about to be created (from its uploaded files) or for an existing object version. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetComparisonUrlOfUploadedFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetComparisonUrlOfUploadedFile/index.md) | Gets a URL of a page that shows the differences between a document file in the vault and a stateless upload identified by its `file_ref`. | `write` `session or assertion` |
| [GetDocEventSubscriptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocEventSubscriptions/index.md) | Gets the caller's event subscriptions for an object. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetDocumentComparisonEnabled](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonEnabled/index.md) | Tells whether document comparison is available in the vault. | `write` `session or assertion` |
| [GetDocumentComparisonUrl](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonUrl/index.md) | Gets a URL of a page that shows the differences between two document files in the vault. | `write` `session or assertion` |
| [GetDocumentComparisonWithTempFileUrl](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonWithTempFileUrl/index.md) | Gets a URL of a page that shows the differences between a document file in the vault and an uploaded temporary file. | `write` `session or assertion` |
| [GetExternalEditingDetails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetExternalEditingDetails/index.md) | Gets the information a client needs to open a file in an external editing system (SharePoint Embedded). | `read` `session or assertion` `idempotent` |
| [GetFileDownloadUrl](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl/index.md) | Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway. | `write` `session or assertion` |
| [GetFileDownloadUrl2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl2/index.md) | Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway. | `write` `session or assertion` |
| [GetFileMalwareInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileMalwareInfo/index.md) | Gets the malware scanning verdict of a file, as an advisory hint for a user interface. | `read` `session or assertion` `idempotent` |
| [GetFileSize](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileSize/index.md) | Gets the size of a specific file version in bytes. | `write` `session or assertion` `returns metadata structure version` |
| [GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems/index.md) | Gets the identities and view IDs of unmanaged items of an external repository. Used by M-Files clients; not for applications. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetLatestFileVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestFileVersion/index.md) | Gets the latest version of a file and the object version it belongs to. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md) | Gets the number and GUID of the latest version of an object. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetLatestVersionCommentOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestVersionCommentOfMultipleObjects/index.md) | Gets the latest version comment of several objects. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMultipleWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions/index.md) | Gets the states and transitions of several workflows in one call, in a compressed binary form. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetMultipleWorkflowStatesAndTransitionsWithRightsCheck](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitionsWithRightsCheck/index.md) | Gets the states and transitions of several workflows in one call, in a compressed binary form, with the user's rights checked. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectFilesForModificationInEventHandler](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFilesForModificationInEventHandler/index.md) | Gets the files of a checked-out object version for modification by an event handler. Used by server-side vault applications; requires the vault-level right to edit and delete all objects. | `write` `session or assertion` `returns metadata structure version` |
| [GetObjectGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectGUID/index.md) | Gets the GUID of an object. | `write` `session or assertion` `returns metadata structure version` |
| [GetObjectHistory2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory2/index.md) | Lists the existing versions of an object with their version information, oldest first. | `write` `session or assertion` `returns metadata structure version` |
| [GetObjectInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfo/index.md) | Gets the version information of one object without its property values. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetObjectInfoAndPropertiesWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata/index.md) | Like GetObjectInfoAndProperties, but each property value also carries its value metadata. | `write` `session or assertion` `returns metadata structure version` |
| [GetObjectsByExternalIds](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectsByExternalIds/index.md) | Finds objects of one object type by their external IDs. | `read` `session or assertion` `idempotent` |
| [GetObjIDByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjIDByGUID/index.md) | Gets the object ID of the object that has the given object GUID. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetPromotedObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPromotedObjects/index.md) | Lists promoted objects of an external repository. Requires full control of the vault; the maximum result count must be 1 to 1000. | `write` `session or assertion` `returns metadata structure version` |
| [GetPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertiesOfMultipleObjects/index.md) | Gets the property values of several specific object versions. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetPropertyValueWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertyValueWithMetadata/index.md) | Gets a property value and its metadata. | `read` `session or assertion` `idempotent` |
| [GetRelationshipsForObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRelationshipsForObject/index.md) | Gets the objects that a specific object version refers to, or that refer to it. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetRemoteRelationshipSourceInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipSourceInfo/index.md) | Gets what another vault needs to create a stub of this object, or to find a matching object. Used by replication and cross-vault relationships; not for applications. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetRemoteRelationshipTargetInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipTargetInfo/index.md) | Finds the local object that matches an object of another vault, or the information for creating a stub of it. Used by replication and cross-vault relationships; not for applications. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetSecurity](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurity/index.md) | Gets the permissions (ACL) of an object version. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetSecurityOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurityOfMultipleObjects/index.md) | Gets the permissions (ACL) of several object versions, in the order of `obj_vers`. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetStateTransitionSignatureSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings/index.md) | Gets the signature settings for a state transition. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetTemplateObjectsForObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplateObjectsForObjectType/index.md) | Gets the template objects of an object type, with the Additional classes value of each. | `write` `session or assertion` `returns metadata structure version` |
| [GetTemplates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplates/index.md) | Gets the templates of an object type, optionally only those of one class or matching keywords. | `write` `session or assertion` `returns metadata structure version` |
| [GetTextContentForFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFile/index.md) | Gets the plain text content of a file version. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetTextContentForFileWithFormat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md) | Gets the text content of a file version as plain text or Markdown, and reports which format was produced. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetTextContentForTemporaryFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile/index.md) | Gets the plain text content of a file uploaded with UploadTempFile. | `write` `session or assertion` |
| [GetVersionCommentHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetVersionCommentHistory/index.md) | Gets the version comments of an object up to a given version, oldest first. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetWorkflowsForClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/index.md) | Gets all the workflows in a format suitable for client. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetWorkflowStateHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStateHistory/index.md) | Gets the workflow state history of an object. | `read` `session or assertion` `idempotent` |
| [HasFileDuplicates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/HasFileDuplicates/index.md) | Tells whether a file with the given content (checksum) already exists in the vault. | `write` `session or assertion` `returns metadata structure version` |
| [KeepUploadSessionAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/KeepUploadSessionAlive/index.md) | Keeps an upload from being removed for inactivity. | `write` `session or assertion` `idempotent` |
| [MigrateObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObject/index.md) | Migrates a promoted object. Requires full control of the vault; used by migration tools. | `write` `session or assertion` `returns metadata structure version` |
| [MigrateObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObjects/index.md) | Migrates and promotes objects. Requires full control of the vault; used by migration tools. | `write` `session or assertion` `returns metadata structure version` |
| [ModifyVersionTags](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ModifyVersionTags/index.md) | Replaces the version tags of an object version with the given set; an empty `tags` clears them. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [PrepareFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PrepareFile/index.md) | Prepares a PDF rendition of a file version and reports its size, extension and timestamp. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [PromoteUnmanagedObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PromoteUnmanagedObject/index.md) | Promotes objects of an external repository (unmanaged objects) to managed M-Files objects by giving them metadata. | `write` `session or assertion` `returns metadata structure version` |
| [RelayMasterStorageOperations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RelayMasterStorageOperations/index.md) | Relays file or object operations to Master Storage. Internal to M-Files; not for applications. | `write` `session or assertion` `idempotent` |
| [RemoveFromRecentlyAccessed](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveFromRecentlyAccessed/index.md) | Removes the specified objects from being shown in 'Recently Accessed by Me'. | `write` `session or assertion` `returns metadata structure version` |
| [RemoveObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjectFile/index.md) | Removes a file from a document. | `write` `session or assertion` `returns metadata structure version` |
| [RemoveObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjects/index.md) | Marks several objects deleted in one transaction. | `write` `session or assertion` `returns metadata structure version` |
| [RemoveProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveProperty/index.md) | Removes one property value from an object version. | `write` `session or assertion` `returns metadata structure version` |
| [RemoveUploadSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md) | Removes an upload and its temporary file. | `write` `session or assertion` `idempotent` |
| [RenameObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RenameObjectFile/index.md) | Renames a document file. | `write` `session or assertion` `returns metadata structure version` |
| [ResolveConflict](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveConflict/index.md) | Resolves a replication conflict between an object and its conflict object. Used by replication tools and M-Files clients; not for applications. | `write` `session or assertion` `returns metadata structure version` |
| [ResolveManagedIDOfPromotedObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveManagedIDOfPromotedObject/index.md) | Gets the managed object ID of an object that had the given unmanaged ID before it was promoted. | `read` `session or assertion` `idempotent` |
| [Rollback](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/Rollback/index.md) | Rolls back to an older version. Creates a new version that is a copy of the specified old version. | `write` `session or assertion` `returns metadata structure version` |
| [SetDocEventSubscriptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetDocEventSubscriptions/index.md) | Replaces the caller's event subscriptions for an object. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [SetExternalObjectID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetExternalObjectID/index.md) | Sets the external ID of an object. | `write` `session or assertion` `returns metadata structure version` |
| [SetFavoritesMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetFavoritesMultiple/index.md) | Adds and removes objects from the favorites collection of the user. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [SetObjectActive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectActive/index.md) | Clears the draft (pending-upload) flag on an object, leaving it checked out. | `write` `session or assertion` |
| [SetObjectGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectGUID/index.md) | Sets the Object GUID of the specified object. NOTE: In general, the identity of an object should remain unchanged. Use this method in special circumstances only. | `write` `session or assertion` `returns metadata structure version` |
| [SetObjectLevelProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectLevelProperty/index.md) | Sets a property that belongs to the object as a whole rather than to one version. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [SetPropertiesWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata/index.md) | Adds, replaces or removes property values of an object, also storing metadata about each value. | `write` `session or assertion` `returns metadata structure version` |
| [SetPropertiesWithMetadataAttributedTo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/index.md) | Sets property values with metadata and records the change as made by a built-in agent user. | `write` `session or assertion` `returns metadata structure version` |
| [SetPropertyValueMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertyValueMetadata/index.md) | Changes the metadata of property values without changing the values. | `write` `session or assertion` |
| [SetTier](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetTier/index.md) | Moves objects between storage tiers. | `write` `session or assertion` |
| [UndeleteObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObjects/index.md) | Restores several deleted objects. Requires the vault-level right to undelete objects. | `write` `session or assertion` `returns metadata structure version` |
| [UndoCheckoutMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckoutMultiple/index.md) | Undoes the check-out of several objects in one call. | `write` `session or assertion` `returns metadata structure version` |
| [UpdateMetadataInFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateMetadataInFile/index.md) | Writes the object's metadata into the properties embedded in its files (for formats that support it). | `write` `session or assertion` `returns metadata structure version` |
| [UpdateObjectModificationInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateObjectModificationInfo/index.md) | Overwrites the creation and last modification information (who and when) of a checked-out object. | `write` `session or assertion` `returns metadata structure version` |
| [UpdateProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateProperty/index.md) | Sets one property value of an object version. | `write` `session or assertion` `returns metadata structure version` |
| [UploadExistingFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadExistingFiles/index.md) | Copies existing file versions into new uploads, for example to create a new object with a copy of a file. | `write` `session or assertion` |
| [UploadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md) | Uploads a block of new content for an existing file of an object that is checked out to the caller. | `write` `session or assertion` `idempotent` |
| [UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md) | Completes an upload made with UploadFile and stores it as the new content of the file. | `write` `session or assertion` `returns metadata structure version` |
---
# IRPCObjectOperations.GetObjectInfoAndProperties
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the version information and the property values of one object, either its latest version
or a specific version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-info-and-properties`
- **Request:** [`GetObjectInfoAndPropertiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md#request)
- **Response:** [`GetObjectInfoAndPropertiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
With `latest_version` true the server returns the latest checked-in version; `doc_version` is
ignored. With `allow_checked_out` also true, a caller who has the object checked out gets the
checked-out version instead.
With `latest_version` false, `doc_version` must be a specific version
(`OBJ_VER_VERSION_TYPE_SPECIFIC`); the `OBJ_VER_VERSION_TYPE_LATEST` marker fails with "Not found.
Invalid object version: -1".
The call fails with "Not found." (0x8004000B) when the object or version does not exist, when the
object ID has the wrong object type, and also when the caller is not allowed to read the object.
To read several objects in one call, or to tolerate missing ones, use
[GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md).
## Request: GetObjectInfoAndPropertiesRequest
> Nested 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 object: object type ID in `type`, object ID in `item_id.internal_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. |
| `latest_version` | `bool` | True to read the latest checked-in version (or the caller's checked-out version, see `allow_checked_out`). False to read the version in `doc_version`. |
| `allow_checked_out` | `bool` | Used with `latest_version`. True to get the checked-out version when the object is checked out to the caller. A version checked out to another user is never returned. |
| `doc_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The specific version to read when `latest_version` is false (`OBJ_VER_VERSION_TYPE_SPECIFIC` and `internal_version`). Ignored when `latest_version` is true. |
| `doc_version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `doc_version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `doc_version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `doc_version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetObjectInfoAndPropertiesResponse
> Nested 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_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of the returned version, including its files. |
| `object_info.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_info.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_info.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_info.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_info.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_info.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_info.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_info.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_info.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_info.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_info.version_info.class_id` | `int32` | The class ID of the version. |
| `object_info.version_info.version_guid` | `string` | The GUID of this version. |
| `object_info.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_info.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `property_array[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The property values of the returned version. |
| `property_array[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `property_array[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `property_array[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property_array[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property_array[].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. |
## Related methods
- [GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md): Gets the version information and the property values of several objects in one call. The preferred way to read objects.
- [GetObjectInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfo/index.md): Gets the version information of one object without its property values.
- [GetObjectInfoAndPropertiesWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata/index.md): Like GetObjectInfoAndProperties, but each property value also carries its value metadata.
---
# IRPCObjectOperations.GetObjectVersionAndPropertiesOfMultipleObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the version information and the property values of several objects in one call. The
preferred way to read objects.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-version-and-properties-of-multiple-objects`
- **Request:** [`GetObjectVersionAndPropertiesOfMultipleObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md#request)
- **Response:** [`GetObjectVersionAndPropertiesOfMultipleObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`objects[i]` and `properties[i]` belong to the same object.
**Latest versions.** With `latest_versions` true the version part of each `obj_vers` item is
ignored: the `OBJ_VER_VERSION_TYPE_LATEST` marker or an unset version both work. Each object may
appear only once ("The parameter is incorrect. (Duplicate objects.)").
**Specific versions.** With `latest_versions` false every item must name a specific version; the
`OBJ_VER_VERSION_TYPE_LATEST` marker fails with "The parameter is incorrect.".
**Missing objects.** By default the whole call fails with "Not found." if any object or version
does not exist or cannot be read by the caller. With `allow_missing_object_versions` true those
items are left out of the response, so the response can be shorter than the request and its
positions do not match the request. Match the results by `object_info.obj_id`.
The server does not cap the number of objects in a request.
## Request: GetObjectVersionAndPropertiesOfMultipleObjectsRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The objects to read. With `latest_versions` true, only `obj_id` is used. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `latest_versions` | `bool` | True to read the latest checked-in version of each object (see `allow_checked_out`). False to read the specific versions in `obj_vers`. |
| `allow_checked_out` | `bool` | Used with `latest_versions`. True to get the checked-out version of the objects that are checked out to the caller. A version checked out to another user is never returned. |
| `allow_missing_object_versions` | `bool` | True to leave out the objects that do not exist or that the caller cannot read, instead of failing the whole call. The response is then shorter than the request. |
## Response: GetObjectVersionAndPropertiesOfMultipleObjectsResponse
> Nested 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 [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of each returned object, including its files. |
| `objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `objects[].object_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 object (e.g. is the object deleted or a stub). |
| `objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `properties[]` | repeated [`PropertyValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueArray/index.md) | The property values of each returned object, in the same order as `objects`. |
| `properties[].value[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values. |
| `properties[].value[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
---
# IRPCObjectOperations.GetObjectDataOfMultipleObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectDataOfMultipleObjects/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets selected data of several objects: version information, properties, ACL, the caller's
permissions, relationships, version comments and more, with a result or an error per object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectDataOfMultipleObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-data-of-multiple-objects`
- **Request:** [`GetObjectDataOfMultipleObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectDataOfMultipleObjects/index.md#request)
- **Response:** [`GetObjectDataOfMultipleObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectDataOfMultipleObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Choose this method when you need more than properties, or when you want a per-object error
instead of a failed or shortened response.
**Results.** `results` has exactly one item per requested object, in the request order.
`results[i].obj_ver` repeats the request; `results[i].object_data.obj_ver` is the version that
was actually read. A result has either `object_data` or `error_info`.
**What is returned.** Only the data named in `data_request.required_data_flags` or
`optional_data_flags`. With no flags at all, `object_data` holds only the resolved `obj_ver`,
which is a cheap way to resolve the latest versions of many objects. If required data is
missing, the object gets `error_info` instead. Relationships, collection members and version
comments were returned only when requested in `required_data_flags`.
**Versions.** `data_request.version_type` defaults to
`OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_SPECIFIC_VERSIONS`, which needs specific versions in
`obj_vers`; the `OBJ_VER_VERSION_TYPE_LATEST` marker then fails with "The parameter is incorrect.".
Use `OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_LATEST_VERSIONS` (includes a version checked out to
the caller) or `OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_LATEST_CHECKED_IN_VERSIONS` to read the
latest versions. An object or version may appear only once ("Duplicate object IDs or
versions.").
**Errors.** With the default error tolerance the whole call fails if any object is missing. With
`OBJECT_VERSION_DATA_REQUEST_ERROR_TOLERANCE_ALLOW_MISSING_OBJECT_VERSIONS`, an object that does
not exist or that the caller cannot read gets `error_info.error_code` 0x8004000B ("Not found.")
and no `object_data`.
## Request: GetObjectDataOfMultipleObjectsRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The objects. With a latest version type, only `obj_id` is used. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `data_request` | [`ObjectVersionDataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionDataRequest/index.md) | What to return, which versions to read and how to handle missing objects. Set at least `required_data_flags` or `optional_data_flags`, and `version_type`. |
| `data_request.required_data_flags` | [`OBJECTDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTDATAREQUESTFLAGS/index.md) | Specifies the required object information. |
| `data_request.required_data_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `data_request.required_data_flags.object_version` | `bool` | Object information is requested, e.g. ObjectVersionEx. |
| `data_request.required_data_flags.properties` | `bool` | Property values are requested, e.g. PropertyValueArray. |
| `data_request.required_data_flags.acl` | `bool` | Access control list is requested, e.g. ACL. |
| `data_request.required_data_flags.current_user_permissions` | `bool` | Object permissions for client is requested, e.g. ObjectPermissionsForClient. |
| `data_request.required_data_flags.properties_for_display` | `bool` | Display properties are requested, e.g. PropertyValueArray. |
| `data_request.required_data_flags.relationships` | `bool` | Related objects are requested, e.g. RelationshipGroup. |
| `data_request.required_data_flags.collection_member_relationships` | `bool` | Collection member objects are requested, e.g. RelationshipGroup. |
| `data_request.required_data_flags.comments` | `bool` | Comment history is requested, e.g. ObjVerProperties. |
| `data_request.required_data_flags.user_event_subscriptions` | `bool` | Event subscription is requested, e.g. EventSubscription. |
| `data_request.required_data_flags.object_activities` | `bool` | ObjectActivities is requested, e.g. ObjectActivitiesResponse. |
| `data_request.required_data_flags.latest_version_comment` | `bool` | Latest version comment is requested, e.g. LatestVersionComment. |
| `data_request.optional_data_flags` | [`OBJECTDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTDATAREQUESTFLAGS/index.md) | Specifies the optional object information. |
| `data_request.optional_data_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `data_request.optional_data_flags.object_version` | `bool` | Object information is requested, e.g. ObjectVersionEx. |
| `data_request.optional_data_flags.properties` | `bool` | Property values are requested, e.g. PropertyValueArray. |
| `data_request.optional_data_flags.acl` | `bool` | Access control list is requested, e.g. ACL. |
| `data_request.optional_data_flags.current_user_permissions` | `bool` | Object permissions for client is requested, e.g. ObjectPermissionsForClient. |
| `data_request.optional_data_flags.properties_for_display` | `bool` | Display properties are requested, e.g. PropertyValueArray. |
| `data_request.optional_data_flags.relationships` | `bool` | Related objects are requested, e.g. RelationshipGroup. |
| `data_request.optional_data_flags.collection_member_relationships` | `bool` | Collection member objects are requested, e.g. RelationshipGroup. |
| `data_request.optional_data_flags.comments` | `bool` | Comment history is requested, e.g. ObjVerProperties. |
| `data_request.optional_data_flags.user_event_subscriptions` | `bool` | Event subscription is requested, e.g. EventSubscription. |
| `data_request.optional_data_flags.object_activities` | `bool` | ObjectActivities is requested, e.g. ObjectActivitiesResponse. |
| `data_request.optional_data_flags.latest_version_comment` | `bool` | Latest version comment is requested, e.g. LatestVersionComment. |
| `data_request.version_type` | [`ObjectVersionDataRequestVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjectVersionDataRequestVersionType/index.md) | Specifies the version type to search for. Values: `OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_SPECIFIC_VERSIONS` (0), `OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_LATEST_VERSIONS` (1), `OBJECT_VERSION_DATA_REQUEST_VERSION_TYPE_LATEST_CHECKED_IN_VERSIONS` (2). |
| `data_request.error_tolerance` | [`ObjectVersionDataRequestErrorTolerance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjectVersionDataRequestErrorTolerance/index.md) | Specifies how error cases are handled during the request. Values: `OBJECT_VERSION_DATA_REQUEST_ERROR_TOLERANCE_FAIL_ON_ANY_ERROR` (0), `OBJECT_VERSION_DATA_REQUEST_ERROR_TOLERANCE_ALLOW_MISSING_OBJECT_VERSIONS` (1). |
| `data_request.identity_type` | [`ObjectVersionDataRequestIdentityType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjectVersionDataRequestIdentityType/index.md) | Specifies how objects with changed identities are handled. Values: `OBJECT_VERSION_DATA_REQUEST_IDENTITY_TYPE_SPECIFIC` (0), `OBJECT_VERSION_DATA_REQUEST_IDENTITY_TYPE_MANAGED_IF_AVAILABLE` (1). |
| `data_request.object_activities_parameters` | [`ObjectVersionActivityRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionActivityRequest/index.md) | Specifies the required object version activity input. |
| `data_request.object_activities_parameters.category_filter` | [`OBJECTVERSIONACTIVITYCATEGORYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTVERSIONACTIVITYCATEGORYFLAGS/index.md) | Category flags. |
| `data_request.object_activities_parameters.limit` | `uint32` | Maximum number of object version activities to be included. |
| `data_request.object_activities_parameters.offset_obj_ver_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | Starting version for object version activities. 0 or missing means no offset. |
## Response: GetObjectDataOfMultipleObjectsResponse
> Nested 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 [`ObjectVersionDataResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionDataResult/index.md) | One result per requested object, in the request order. |
| `results[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Requested object version. |
| `results[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `results[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `results[].object_data` | [`ObjectVersionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionData/index.md) | The pointer to the result data details. Equals to null for the failed result. |
| `results[].object_data.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The actual resolved object version. |
| `results[].object_data.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The pointer to object info. Null pointer, if data was not requested. |
| `results[].object_data.properties` | [`PropertyValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueArray/index.md) | The pointer to property values. Null pointer, if data was not requested. |
| `results[].object_data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The pointer to ACL. Null pointer, if data was not requested. |
| `results[].object_data.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | The pointer to object permissions for client. Null pointer, if data was not requested. |
| `results[].object_data.properties_for_display` | [`PropertyValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueArray/index.md) | Property values for display, or an empty array. Null pointer, if data was not requested. |
| `results[].object_data.relationships[]` | repeated [`RelationshipGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RelationshipGroup/index.md) | List of related objects(From and To) and collection members. Null pointer, if data was not requested. |
| `results[].object_data.comments` | [`VersionCommentArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VersionCommentArray/index.md) | List of version comments. Null pointer, if data was not requested. |
| `results[].object_data.user_event_subscriptions[]` | repeated [`EventSubscription`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventSubscription/index.md) | The pointer to event subscription. Null pointer, if data was not requested. |
| `results[].object_data.object_activities` | [`ObjectVersionActivityResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionActivityResponse/index.md) | The pointer to object version activity. |
| `results[].object_data.latest_version_comment` | [`LatestVersionComment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LatestVersionComment/index.md) | The pointer to latest version comment. Null pointer, if data was not requested. |
| `results[].error_info` | [`ErrorInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ErrorInfo/index.md) | The pointer to the error information. Equals to null for the successful result. |
| `results[].error_info.error_code` | `int32` | The error code (HRESULT value). |
---
# IRPCObjectOperations.GetProperties
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the property values of one specific object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetProperties`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-properties`
- **Request:** [`GetPropertiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md#request)
- **Response:** [`GetPropertiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`obj_ver` must name a specific version (`OBJ_VER_VERSION_TYPE_SPECIFIC` and `internal_version`).
The `OBJ_VER_VERSION_TYPE_LATEST` marker, `OBJ_VER_VERSION_TYPE_ANY` and an unset version all fail
with "Not found." (0x8004000B). To read the latest properties, use
[GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md)
with `latest_versions` true, or get the version number from
[GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md) first.
A caller who cannot read the object gets "Access denied." (0x800407E4).
## Request: GetPropertiesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callimp` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object and a specific version of it. The latest-version marker is not accepted. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetPropertiesResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The property values of the version. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
## Related methods
- [GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md): Gets the version information and the property values of several objects in one call. The preferred way to read objects.
- [GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md): Gets the number and GUID of the latest version of an object.
- [GetPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertiesOfMultipleObjects/index.md): Gets the property values of several specific object versions.
---
# IRPCObjectOperations.GetObjectFiles
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFiles/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the files of a specific object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectFiles`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-files`
- **Request:** [`GetObjectFilesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFiles/index.md#request)
- **Response:** [`GetObjectFilesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFiles/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`obj_ver` must name a specific version; the `OBJ_VER_VERSION_TYPE_LATEST` marker fails with "Not
found.". You often do not need this call: the version information returned by the read methods
([ObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) `files`) already contains the same list. Pass a
returned `File.file_ver` to
[DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md) to download the file.
A caller who cannot read the object gets "Access denied.".
## Request: GetObjectFilesRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object and a specific version of it. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetObjectFilesResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of the version, with their IDs, versions, sizes and MD5 checksums. |
| `files[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `files[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `files[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `files[].file_ver.internal_version` | `int32` | The file version number. |
| `files[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `files[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `files[].title` | `string` | The file name without the extension. |
| `files[].extension` | `string` | The file name extension without the dot, for example "pdf". |
| `files[].size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `files[].size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `files[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `files[].accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `files[].written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `files[].changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `files[].guid` | `string` | GUID of the file. |
| `files[].md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `files[].is_missing` | `bool` | True, if the file is missing. |
| `files[].is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `files[].flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `files[].flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `files[].flags.can_be_edited_externally` | `bool` | Next available value. |
| `files[].master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
## Related methods
- [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md): Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum.
- [GetObjectFilesForModificationInEventHandler](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFilesForModificationInEventHandler/index.md): Gets the files of a checked-out object version for modification by an event handler. Used by server-side vault applications; requires the vault-level right to edit and delete all objects.
---
# IRPCObjectOperations.DownloadFile_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Opens a download session for a file version and returns its ID, the content size and, on
request, its MD5 checksum.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadFile_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-file_-begin`
- **Request:** [`DownloadFile_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md#request)
- **Response:** [`DownloadFile_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Downloading a file takes three calls:
1. `DownloadFile_Begin` with the file's `obj_file_ver` and `prepare_file_for_downloading` true.
2. [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md) with the
returned `download_id`, from offset 0, until a block shorter than requested comes back. Blocks
are at most 4 MiB.
3. [DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md). When the whole
file was read in order from the start, the server has already closed the session; the call
still succeeds, so always make it.
Take `obj_file_ver.file_ver` from the version information of the object
([File](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) `file_ver`). It must be a specific file version:
`FILE_VER_TYPE_LATEST` fails with "Not found. (File -0 not found.)".
**Formats.** `FILE_FORMAT_NATIVE` downloads the file as stored. `FILE_FORMAT_PDF` and
`FILE_FORMAT_DISPLAY_ONLY_PDF` download a PDF rendition that the server creates if needed (for
example from Office files); `file_outline.size` is then the size of the PDF. `FILE_FORMAT_PLAIN_TEXT`
and `FILE_FORMAT_MARKDOWN` are not supported here ("The requested file format ... is not
supported."); use
[GetTextContentForFileWithFormat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md).
**Checksum.** `file_outline.md5_checksum` is filled only when `need_checksum` is true; otherwise it
is 32 zeros. For the PDF formats the server currently returns the checksum of the native file,
not of the PDF, so do not verify a PDF download against it.
**Session.** A download session belongs to the login session that opened it, on the server that
opened it. An unused session is closed after about 10 minutes (server default).
## Request: DownloadFile_BeginRequest
> Nested 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_file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and the specific file version, as in `File.file_ver`. |
| `obj_file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver.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_file_ver.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_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `format` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | `FILE_FORMAT_NATIVE` (default), `FILE_FORMAT_PDF` or `FILE_FORMAT_DISPLAY_ONLY_PDF`. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
| `prepare_file_for_downloading` | `bool` | Must be true to download. False only checks the caller's access and records the file as accessed; `download_id` is then 0. |
| `need_checksum` | `bool` | True to get the MD5 checksum of the native file in `file_outline.md5_checksum`. |
## Response: DownloadFile_BeginResponse
> Nested 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 for `DownloadFile_ReadBlock` and `DownloadFile_Stop`. 0 if `prepare_file_for_downloading` was false. |
| `file_outline` | [`FileOutline`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileOutline/index.md) | The size of the content to download, in the requested format, and the checksum if requested. |
| `file_outline.size` | `int64` | The size of the content in bytes, in the downloaded format. |
| `file_outline.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | The file size precision. If the file size precision is 'exact', the size can be used for reading the file content. If the precision is 'unknown', the size field should not be used at all. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file_outline.md5_checksum` | `string` | The MD5 checksum as 32 hexadecimal digits, if requested; 32 zeros otherwise. |
| `ov_ex` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of the object that owns the file. |
| `ov_ex.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `ov_ex.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `ov_ex.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `ov_ex.version_info.title` | `string` | The title (name) of the object in this version. |
| `ov_ex.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `ov_ex.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `ov_ex.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `ov_ex.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `ov_ex.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `ov_ex.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `ov_ex.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `ov_ex.version_info.class_id` | `int32` | The class ID of the version. |
| `ov_ex.version_info.version_guid` | `string` | The GUID of this version. |
| `ov_ex.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `ov_ex.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `ov_ex.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `ov_ex.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ov_ex.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ov_ex.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ov_ex.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ov_ex.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ov_ex.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ov_ex.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ov_ex.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ov_ex.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ov_ex.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ov_ex.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ov_ex.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ov_ex.object_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 object (e.g. is the object deleted or a stub). |
| `ov_ex.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ov_ex.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ov_ex.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ov_ex.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ov_ex.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ov_ex.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md): Reads a block of a file from a download session.
- [DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md): Closes a download session.
- [GetTextContentForFileWithFormat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md): Gets the text content of a file version as plain text or Markdown, and reports which format was produced.
- [DownloadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.DownloadFile_ReadBlock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Reads a block of a file from a download session.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-file_-read-block`
- **Request:** [`DownloadFile_ReadBlockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md#request)
- **Response:** [`DownloadFile_ReadBlockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
`block_size` is at most 4 MiB (4194304 bytes); a larger value fails with "The parameter is
incorrect. (Block size exceeded the limit of 4194304 bytes.)". The server returns `block_size`
bytes, or fewer at the end of the file; an `offset` at or past the end returns no data. Blocks can
be read in any order and read again.
When the last block has been read and the file was read in order from offset 0, the server
closes the download session; a later read fails with "Not found. (The specified download session
does not exist.)". Otherwise close it with
[DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md).
The session also serves the downloads opened by
[DownloadTempFileFromUpload_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md).
## Request: DownloadFile_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` | From `DownloadFile_Begin` or `DownloadTempFileFromUpload_Begin`. |
| `block_size` | `uint32` | The number of bytes to read, at most 4194304 (4 MiB). |
| `offset` | `int64` | The byte offset to read from. |
## Response: DownloadFile_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; empty past the end. |
## Related methods
- [DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md): Closes a download session.
- [DownloadTempFileFromUpload_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md): Opens a download session for a committed upload, to read it back or as a PDF, without creating an object.
- [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md): Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum.
- [DownloadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.DownloadFile_Stop
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Closes a download session.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadFile_Stop`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-file_-stop`
- **Request:** [`DownloadFile_StopRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md#request)
- **Response:** [`DownloadFile_StopResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Closing a session that does not exist, for example one the server already closed after the last
block was read, succeeds.
## Request: DownloadFile_StopRequest
> Nested 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 ID of the download session. |
## Response: DownloadFile_StopResponse
No fields.
## Related methods
- [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md): Reads a block of a file from a download session.
- [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md): Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum.
- [DownloadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.UploadTempFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/
Badges: `Vault API / core` `write` `session or assertion` `idempotent`
Uploads a block of a file to a temporary upload session on the server. The upload can then be
used as the content of a new object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UploadTempFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-temp-file`
- **Request:** [`UploadTempFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md#request)
- **Response:** [`UploadTempFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Upload a file in one or more calls:
1. The first call has `upload_id` 0, `offset` 0 and the `total_size_in_bytes` of the file. It
returns the new `upload_id`.
2. Further calls pass that `upload_id` and the `offset` of their block.
3. [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) completes the
upload.
The committed upload can be used by
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) (`files` with
`OBJ_FILE_SOURCE_TYPE_UPLOADED_FILE` or `..._UPLOADED_FILES` and the `upload_id`), which consumes
it, and by [DownloadTempFileFromUpload_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md)
and [GetTextContentForTemporaryFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile/index.md).
An upload that is not committed cannot be used ("The process cannot access the file because it is
being used by another process.").
**Session.** The upload belongs to the calling login session, on the server that received the
first block; another login session gets "Not found. (The specified upload session does not
exist.)". An upload that is not used for about 10 minutes (server default) is removed: call
[KeepUploadSessionAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/KeepUploadSessionAlive/index.md) at the interval
given in `SessionData.keep_upload_session_alive_interval_in_seconds` if you keep it longer.
Remove uploads you do not use with
[RemoveUploadSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md). Anonymous sessions
cannot upload.
Each request is limited by the server's maximum gRPC message size (48 MiB by default).
## Request: UploadTempFileRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | 0 to start a new upload; the returned ID for the following blocks. |
| `total_size_in_bytes` | `int64` | The size of the whole file. Read only in the first call. |
| `offset` | `int64` | The position of this block in the file. Must be 0 in the first call. Use multiples of 4096 bytes for all blocks but the last. |
| `data` | `bytes` | The bytes of this block. |
| `temp_extension` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | The file name extension of the upload, without the dot (for example "pdf"). Set it in the first call. `DownloadTempFileFromUpload_Begin` returns it as `file_extension`. |
| `temp_extension.value` | `string` | String. |
## Response: UploadTempFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The ID of the upload. |
## Related methods
- [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [DownloadTempFileFromUpload_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md): Opens a download session for a committed upload, to read it back or as a PDF, without creating an object.
- [GetTextContentForTemporaryFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile/index.md): Gets the plain text content of a file uploaded with UploadTempFile.
- [KeepUploadSessionAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/KeepUploadSessionAlive/index.md): Keeps an upload from being removed for inactivity.
- [RemoveUploadSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md): Removes an upload and its temporary file.
---
# IRPCObjectOperations.UploadTempFileCommit
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/
Badges: `Vault API / core` `write` `session or assertion` `idempotent`
Completes an upload made with UploadTempFile.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UploadTempFileCommit`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-temp-file-commit`
- **Request:** [`UploadTempFileCommitRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md#request)
- **Response:** [`UploadTempFileCommitResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
`logical_size` must equal the number of bytes uploaded. Otherwise the call fails with "File size
mismatch." (0x8004003D) and the server **removes the upload**, so it must be uploaded again.
Commit only once: a second commit of the same upload also fails with "File size mismatch." and
removes it. The response is empty; the upload is used by its `upload_id`.
## Request: UploadTempFileCommitRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The ID from `UploadTempFile`. |
| `logical_size` | `int64` | The total number of bytes uploaded. |
| `low_digest` | `int64` | Leave 0. |
| `high_digest` | `int64` | Not checked by this method; leave 0. |
## Response: UploadTempFileCommitResponse
No fields.
## Related methods
- [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
---
# IRPCObjectOperations.AddObjectWithFiles
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a new object, optionally with its files, and optionally checks it in.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddObjectWithFiles`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object-with-files`
- **Request:** [`AddObjectWithFilesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md#request)
- **Response:** [`AddObjectWithFilesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
This is the general way to create an object. One call creates the object checked out, attaches
the files, runs the creation event handlers and, if `check_in` is true, checks the object in. All
of it happens in one transaction: if any step fails, no object is created (the object ID
that was reserved for it is not reused).
**Required properties.** Send at least:
| Property definition | ID | Notes |
|---|---|---|
| Class | 100 | A lookup into value list 1 (classes). Without it: "Class was not specified." |
| Name or title | 0 | Or the property the class names as its name property (`name_property_def`). |
| Single file | 22 | Required for documents (object type 0) and other types that can have files. |
| Required properties of the class | | `is_required` in the class's `associated_property_defs`. |
A missing required property fails with "The mandatory property value "" is missing." Get the
class and its required properties with
[GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md). The server
fills the automatic properties (Created, Created by, Last modified, ...) itself.
**Set `acl`.** The server stores the ACL you send as the object's permissions. If `acl` is unset,
the object gets an empty ACL: after check-in only users with a vault-level right to see all objects
can see it, and not even its creator. To give the object ordinary permissions, send the
`acl_for_objects` of a named ACL from
[GetNamedACLs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md) (call it with `include_builtin: true`),
for example ID -1, "Full control for all internal users". For a named ACL that does not depend
on the current user, a link alone is enough:
`acl { custom_component { has_named_acl: true named_acl_id: -1 } }`. A link alone to the
built-in "Only for me" (-20) leaves the object without permissions; send its full
`acl_for_objects`, which names the user.
**Single-file documents.** With Single file (22) true, the object must end up with exactly one
file: true without a file source fails with "Cannot set document to single-file mode." At
check-in, the file of a single-file document takes the object's title as its file title; the
`title` given in the file source is not kept.
**File sources** (`files.type` and the matching `files.data` member):
* `OBJ_FILE_SOURCE_TYPE_FILE_CONTENT` with `file_content`: the file bytes inline in the request.
The simplest way to create a document with one file. Only for a single-file document of object
type 0 (Document); otherwise the call fails with invalid argument. At most 10 MiB; `title` is
required.
* `OBJ_FILE_SOURCE_TYPE_UPLOADED_FILE` with `uploaded_file`, or `OBJ_FILE_SOURCE_TYPE_UPLOADED_FILES`
with `uploaded_files`: content uploaded first. Give either `upload_id` (from
[UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) followed by
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md)) or `file_ref`
(from [FileUploadWhole](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/index.md) or
[FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md), on servers that report
`ServerVaultCapabilities.file_upload_stateless_supported`; stateless uploads are switched off by
default in M-Files Server 26.11). An upload session that was not committed fails ("The process
cannot access the file because it is being used by another process."), and an upload is
consumed by the object
it is attached to: a second object cannot use the same `upload_id`.
* `OBJ_FILE_SOURCE_TYPE_BLANK_TEMPLATE` (`blank_template.name`) or
`OBJ_FILE_SOURCE_TYPE_USER_DEFINED_TEMPLATE` (`user_defined_template.obj_id`, a template object,
see [GetTemplates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplates/index.md)): the file is copied from a
template.
* `OBJ_FILE_SOURCE_TYPE_EMPTY_FILES` with `empty_files`: files with a title and extension but no
content yet. Only together with `draft: true`.
* `files` unset or `OBJ_FILE_SOURCE_TYPE_UNDEFINED`: no files. Set Single file (22) to false.
**The response.** `is_visible_to_user` tells whether the creator could see the new object before
it was checked in. When the checked-in object is not visible to the caller (for example because
`acl` was unset), `created_object` carries only the object ID and version number, with no
properties, files or title. Read the object again with
[GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md) when
you need its full state.
**Workflow.** The class's default workflow is not applied by the server when the class does not
force a workflow: send Workflow (38) and Workflow State (39) yourself.
A state of another workflow wins: the server sets Workflow (38) to
the state's workflow. Sending only a state also sets the workflow; sending only a workflow leaves
the state empty.
**Permissions.** The user needs the vault-level right to create objects and a license that allows
modifications.
## Request: AddObjectWithFilesRequest
> 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 |
|---|---|---|
| `object_type_id` | `int32` | The object type of the new object: 0 for documents, or the ID of another object type from [GetObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md). |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values of the new object. Include Class (100), the name property (usually Name or title, 0), Single file (22) for types that can have files, and the properties the class requires. Values need no `value_metadata` here. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of the new object. If unset, the object gets an empty ACL and becomes invisible to its creator after check-in. Send a named ACL's `acl_for_objects`, or a link to a named ACL in `custom_component`. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Optional extra checks; for example `require_read_access_after_operation` makes the call fail if the caller could not see the object afterwards. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | True to check the new object in. False leaves it checked out to the caller, visible only to the caller until checked in; [UndoCheckout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md) then discards the whole object. |
| `files` | [`ObjFileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSource/index.md) | Where the files of the new object come from. Unset for an object without files. |
| `files.type` | [`ObjFileSourceType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjFileSourceType/index.md) | Which member of `data` is used. Must match the member that is set. Values: `OBJ_FILE_SOURCE_TYPE_UNDEFINED` (0), `OBJ_FILE_SOURCE_TYPE_BLANK_TEMPLATE` (1), `OBJ_FILE_SOURCE_TYPE_USER_DEFINED_TEMPLATE` (2), `OBJ_FILE_SOURCE_TYPE_UPLOADED_FILE` (3), `OBJ_FILE_SOURCE_TYPE_UPLOADED_FILES` (4), `OBJ_FILE_SOURCE_TYPE_EMPTY_FILES` (5), `OBJ_FILE_SOURCE_TYPE_FILE_CONTENT` (6). |
| `files.data` | [`ObjFileSourceUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md) | The source data; set the member that matches `type`. |
| `files.data.blank_template` | [`ObjFileSourceUnion.BlankTemplateData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-BlankTemplateData) (oneof data) | Blank template object file source. |
| `files.data.user_defined_template` | [`ObjFileSourceUnion.UserDefinedTemplateData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-UserDefinedTemplateData) (oneof data) | User defined template object file source. |
| `files.data.uploaded_file` | [`ObjFileSourceUnion.UploadedFileData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-UploadedFileData) (oneof data) | Uploaded object file source. |
| `files.data.uploaded_files` | [`ObjFileSourceUnion.UploadedFilesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-UploadedFilesData) (oneof data) | Uploaded object file source with multiple files. |
| `files.data.empty_files` | [`ObjFileSourceUnion.EmptyFilesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-EmptyFilesData) (oneof data) | Empty object file source (one or more files). Only the title and extension of each file are known; there is no upload id or size because the file contents have not been uploaded yet. This type may only be used when the object is created as a draft (the draft flag must be set); otherwise the request is rejected. |
| `files.data.file_content` | [`ObjFileSourceUnion.FileContentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-FileContentData) (oneof data) | Inline file content object file source. |
| `draft` | `bool` | True to create the object checked out and flagged as a draft whose file content is uploaded later (used with `OBJ_FILE_SOURCE_TYPE_EMPTY_FILES`). Leave `check_in` false; clear the flag with [SetObjectActive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectActive/index.md). |
## Response: AddObjectWithFilesResponse
> 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 |
|---|---|---|
| `is_visible_to_user` | `bool` | True if the caller could see the new object before check-in. It does not guarantee that `created_object` is complete; see the remarks. |
| `created_object` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The new object version with its properties and ACL. If the checked-in object is not visible to the caller, only its ID and version number are set. |
| `created_object.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `created_object.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `created_object.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `created_object.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `created_object.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `created_object.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `created_object.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_object.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `created_object.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `created_object.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `created_object.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `created_object.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## 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.
- [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.
- [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
- [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.
- [IRPCFileTransferStreaming.FileUploadWhole](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/index.md): Uploads a whole file by streaming its content.
- [IRPCFileTransfer.FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md): Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or AddObjectWithFiles for that.
- [GetTemplates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplates/index.md): Gets the templates of an object type, optionally only those of one class or matching keywords.
- [GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md): Gets the version information and the property values of one object, either its latest version or a specific version.
- [AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
- [AddObjectWithFilesWithPropertyMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/index.md): Creates a new object with files, storing metadata about each property value (who or what set it, why, and with what confidence).
---
# IRPCObjectOperations.AddObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a new object without files.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object`
- **Request:** [`AddObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md#request)
- **Response:** [`AddObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Same as [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) without a file
source: the same required properties apply. **Set `acl`**: an unset `acl` gives the object an
empty ACL, and once it is checked in only users with the vault-level right to see all objects can
see it, not even its creator. A document created this way has no
files, so Single file (22) must be false; true fails with "Cannot set document to single-file
mode." Use AddObjectWithFiles to create a document with files.
## Request: AddObjectRequest
> 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_type` | `int32` | The object type of the new object (0 for documents). |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values of the new object. Include Class (100), the name property and the properties the class requires; Single file (22) must be false for documents. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of the new object. Unset gives an empty ACL; see [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md). |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | True to check the new object in; false leaves it checked out to the caller. |
## Response: AddObjectResponse
> 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 |
|---|---|---|
| `latest_visible` | `bool` | True if the latest version of the new object is visible to the caller. |
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The new object version with its properties and ACL, if `latest_visible` is true. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [AddObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md): Adds new document file to a document.
- [AddObjectWithFilesWithPropertyMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/index.md): Creates a new object with files, storing metadata about each property value (who or what set it, why, and with what confidence).
---
# IRPCObjectOperations.CheckOut
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Checks out one object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CheckOut`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-out`
- **Request:** [`CheckOutRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md#request)
- **Response:** [`CheckOutResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Checking out creates a new version (latest checked-in version + 1) that only the caller can
change. [GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md)
returns the checked-out version only with `allow_checked_out: true`.
The check-out is bound to the user and to
the computer name of the session, which is `environment_data.client_name` of the
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) call: another session of the same user with a different
`client_name` fails with "The object was checked out to another computer ()."
Errors: "The object is already checked out." if the caller already has it checked out,
"The object is checked out to another user." if someone else does.
You rarely need CheckOut for metadata changes:
[SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md) with
`allow_modifying_checked_in_object` checks out, changes and checks in in one call. Check out
explicitly to make several changes (properties and files) into one new version.
## Request: CheckOutRequest
> Nested 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 object to check out. The latest checked-in version is checked out. |
| `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. |
## Response: CheckOutResponse
> 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 |
|---|---|---|
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The checked-out version: its version number is the one to pass to SetProperties, AddObjectFile and CheckIn. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `previous_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The checked-in version the check-out started from. |
| `previous_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `previous_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `previous_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `previous_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `previous_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `previous_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `previous_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `previous_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `previous_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `previous_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `previous_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `previous_version.version_info.class_id` | `int32` | The class ID of the version. |
| `previous_version.version_info.version_guid` | `string` | The GUID of this version. |
| `previous_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `previous_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `previous_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `previous_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `previous_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `previous_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `previous_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `previous_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `previous_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `previous_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `previous_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `previous_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `previous_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `previous_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `previous_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `previous_version.object_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 object (e.g. is the object deleted or a stub). |
| `previous_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `previous_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `previous_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `previous_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `previous_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `previous_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md): Gets the number and GUID of the latest version of an object.
- [IRPCLogin.LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
- [CheckOutMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOutMultiple/index.md): Checks out several objects in one call.
---
# IRPCObjectOperations.CheckIn
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Checks in one object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CheckIn`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-in`
- **Request:** [`CheckInRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md#request)
- **Response:** [`CheckInResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`obj_ver` must name the checked-out version by number. The `OBJ_VER_VERSION_TYPE_LATEST` marker
fails with "Not found. Invalid object version: -1", and the latest checked-in version fails with
"... the version you are attempting to access is not the current checked-out version."
Get the checked-out version number from the CheckOut response or from
[GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md) with
`allow_checked_out: true`.
If nothing was changed since the check-out, the server undoes the check-out instead of creating a
version: the latest version stays the one before the check-out. Properties sent in
`properties` are set before check-in and count as a change. Set a version comment by sending
Comment (33, multi-line text) in `properties`.
Files added with [AddObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md) whose content was
never uploaded and committed are dropped at check-in.
Check in from a session of the same user with the same `client_name` as the one that checked
the object out; see [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md).
## Request: CheckInRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The checked-out version, by number. The LATEST marker is not accepted. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values to add or replace before check-in, for example a version comment in Comment (33). Leave empty to check in as is. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: CheckInResponse
> Nested 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_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The object after check-in, with its latest version, properties and ACL. |
| `object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `object_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [GetLatestObjectVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md): Gets the number and GUID of the latest version of an object.
- [AddObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md): Adds new document file to a document.
- [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md): Checks out one object.
- [CheckInMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInMultiple/index.md): Checks in several objects in one call.
- [CheckInExternalChanges](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInExternalChanges/index.md): Creates new versions of objects whose files were changed in an external editing system (SharePoint Embedded co-authoring). No version is created for an object without changes.
---
# IRPCObjectOperations.UndoCheckout
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Undoes the checkout of one object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UndoCheckout`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/undo-checkout`
- **Request:** [`UndoCheckoutRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md#request)
- **Response:** [`UndoCheckoutResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Discards the checked-out version and all changes made to it; the latest checked-in version becomes
the latest version again. For a new object that has never been checked in, undoing the check-out
discards the whole object.
`obj_ver` must name the checked-out version by number; the LATEST marker fails with "Not found.
Invalid object version: -1". Undoing a check-out of an object that is not checked out
fails with "The object is not checked out."
Without `force`, only the user who checked the object out can undo the check-out, from the same
computer. With `force`, the user can undo their own check-out from any computer, and a user with
the vault-level right to force undo check-out (`force_undo_checkout`) can undo anyone's check-out.
## Request: UndoCheckoutRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The checked-out version, by number. The LATEST marker is not accepted. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `force` | `bool` | True to undo a check-out made from another computer, or by another user (requires the vault-level right to force undo check-out). |
## Response: UndoCheckoutResponse
> Nested 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_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The object after the operation. Its `latest_version` carries no property values. |
| `object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `object_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [UndoCheckoutMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckoutMultiple/index.md): Undoes the check-out of several objects in one call.
---
# IRPCObjectOperations.SetProperties
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Adds, replaces or removes property values of an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetProperties`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-properties`
- **Request:** [`SetPropertiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md#request)
- **Response:** [`SetPropertiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
**Checked-in objects.** With `allow_modifying_checked_in_object: true`, the server checks the
object out, applies the change and checks it in, creating exactly one new version. Without it, a
checked-in object fails with "The object is not checked out." Every such call creates a new
version, even when the values do not change.
**Checked-out objects.** If the caller has the object checked out, `obj_ver` must name the
checked-out version; the change goes to that version and no new version is created. Naming the
checked-in version of an object checked out to the caller fails ("... not the current
checked-out version."), and an object checked out to someone else fails with "The object is
checked out to another user."
**Targeting a version.** `obj_ver` must name a version by number: the
`OBJ_VER_VERSION_TYPE_LATEST` marker fails with "The parameter is incorrect." For a
checked-in object, the server always changes the latest version, whatever number you send (even a
number that does not exist yet), unless `fail_if_newer_version_exists` is true: then a number other
than the latest checked-in version fails with "There is a newer version of this object on the
server." Use it for optimistic concurrency: read the version, then write with
`fail_if_newer_version_exists`.
**Adding, replacing and removing.**
* Values in `properties` are added or replace the existing value of the same property definition.
All other properties stay as they are.
* To empty a property, send it with `is_null_value: true` (and its `type`).
* `remove` removes property values from the object. Properties that the object's class lists
cannot be removed, not even optional ones: the call fails with "The property "" cannot be
removed from the object." Set them empty instead.
* `remove_unspecified_properties: true` makes `properties` the full set: every property not in it
and not listed by the class is removed. Class-listed properties stay (with their values or
empty), as do the properties the server maintains. The full set must still include the Class
(100) property, otherwise the call fails with "Class was not specified."; an empty full set
fails with invalid argument. Rarely what you want.
**Single-file documents.** Changing the title of a single-file document with
`allow_modifying_checked_in_object` also renames its file.
**Workflow.** Change the workflow state by setting Workflow State (39), a lookup into value list 8,
or by setting State transition (99), a lookup into value list 17 with a transition ID from
[GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md).
A state change that the workflow does not allow fails with "Access denied. The state transition
" -> " is not allowed." If you change Workflow (38), set the state as well:
the server does not clear or replace a state of the previous workflow. A transition that
requires an electronic signature needs `signature`: the session ID of a second
[LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md) of the same user, made less than 15 seconds earlier; the
server logs that session out. See
[GetStateTransitionSignatureSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings/index.md).
**Permissions.** The caller needs edit access to the object; the server makes an exception that
lets an assignee mark an assignment complete. `allow_missing_required_properties`
requires the vault-level right to change the metadata structure and takes effect only if the vault
allows objects with empty required fields.
Use [SetPropertiesMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/index.md) to change
several objects in one transaction.
## Request: SetPropertiesRequest
> 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 |
|---|---|---|
| `signature` | [`SESSIONID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SESSIONID/index.md) | The session ID of a second LogIn of the same user, made less than 15 seconds before this call, when a workflow state transition requires an electronic signature. Unset otherwise. |
| `signature.value` | `bytes` | 64-byte session ID in RPC interface. 48 bytes in gRPC interface. |
| `obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The version to change, by number: the checked-out version if the caller has the object checked out, otherwise the latest checked-in version. The LATEST marker is not accepted. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `allow_modifying_checked_in_object` | `bool` | True to change a checked-in object: the server checks it out, applies the change and checks it in as one new version. Without it the object must be checked out to the caller. |
| `allow_missing_required_properties` | `bool` | True to allow the object to lack required properties. Requires the vault-level right to change the metadata structure and a vault setting that allows it. |
| `fail_if_newer_version_exists` | `bool` | With `allow_modifying_checked_in_object`, true to fail if `obj_ver` is not the latest checked-in version. Without it, the change goes to the latest version whatever version you name. |
| `version_guid` | `string` | Optional `version_guid` of the version in `obj_ver`. With `fail_if_newer_version_exists`, the call also fails if that version has been replaced (for example by replication conflict resolution). Leave empty normally. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values to add or replace. Other properties stay unchanged. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `remove_unspecified_properties` | `bool` | True to treat `properties` as the full set and remove every other property the class does not list. `properties` must then include Class (100). Leave false. |
| `remove[]` | repeated `int32` | Property definition IDs to remove. Properties listed by the class cannot be removed; set them empty instead. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Optional extra checks, for example `disallow_name_change` or `require_edit_access_after_operation`. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `acl_mode` | [`ACLEnforcingMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ACLEnforcingMode/index.md) | Which ACL the server starts from when it updates the object's permissions. The default, `ACLENFORCING_MODE_USE_PREVIOUS`, uses the object's current ACL; `ACLENFORCING_MODE_USE_PROVIDED` uses `acl`; `ACLENFORCING_MODE_RESET_TO_DEFAULT` uses the ACL calculated from the properties. `ACLENFORCING_MODE_DISALLOW_CHANGES` is rejected as invalid argument. Values: `ACLENFORCING_MODE_USE_PREVIOUS` (0), `ACLENFORCING_MODE_USE_PROVIDED` (1), `ACLENFORCING_MODE_RESET_TO_DEFAULT` (2), `ACLENFORCING_MODE_DISALLOW_CHANGES` (3). |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions to use with `ACLENFORCING_MODE_USE_PROVIDED`. Unset otherwise. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
## Response: SetPropertiesResponse
> Nested 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_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The object after the change: its latest version with properties and ACL. `original_obj_ver` echoes the requested version. |
| `object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `object_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md): Gets the states and transitions of the given workflow.
- [IRPCLogin.LogIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md): Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
- [GetStateTransitionSignatureSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings/index.md): Gets the signature settings for a state transition.
- [SetPropertiesMultiple](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/index.md): If the object is currently checked in, a new checked-in version is created. If the object is currently checked out, the changes are applied to the checked-out version.
- [SetPropertiesWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata/index.md): Adds, replaces or removes property values of an object, also storing metadata about each value.
- [SetPropertiesWithMetadataAttributedTo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/index.md): Sets property values with metadata and records the change as made by a built-in agent user.
---
# IRPCObjectOperations.SetPropertiesMultiple
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
If the object is currently checked in, a new checked-in version is created.
If the object is currently checked out, the changes are applied to the checked-out version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetPropertiesMultiple`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-properties-multiple`
- **Request:** [`SetPropertiesMultipleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/index.md#request)
- **Response:** [`SetPropertiesMultipleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesMultiple/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Changes several objects in one transaction. Each entry in `properties` has the same meaning as the
fields of [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md), with the same rules
for versions, removal and check-out. If any entry fails, nothing is changed. Name each
object only once: two entries for the same object fail with "Not found."
`results` is in the order of `properties`.
## Request: SetPropertiesMultipleRequest
> 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 |
|---|---|---|
| `properties[]` | repeated [`SetPropertiesParams`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetPropertiesParams/index.md) | One set of changes per object; see [SetPropertiesParams](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetPropertiesParams/index.md). Each object at most once. |
| `properties[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The version to change, by number: the checked-out version if the caller has the object checked out, otherwise the latest checked-in version. The LATEST marker is not accepted. |
| `properties[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `properties[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `properties[].allow_modifying_checked_in_object` | `bool` | True to change a checked-in object: the server checks it out, applies the change and checks it in as one new version. |
| `properties[].fail_if_not_latest_checked_in_version` | `bool` | With `allow_modifying_checked_in_object`, true to fail if `obj_ver` is not the latest checked-in version. |
| `properties[].object_version_guid` | `string` | Optional `version_guid` of the version in `obj_ver`, checked together with `fail_if_not_latest_checked_in_version`. Leave empty normally. |
| `properties[].set_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values to add or replace. Other properties stay unchanged. |
| `properties[].set_properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].set_properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].is_full_set` | `bool` | True to treat `set_properties` as the full set and remove every other property the class does not list. `set_properties` must then include Class (100). Leave false. |
| `properties[].remove_properties[]` | repeated `int32` | Property definition IDs to remove. Properties listed by the class cannot be removed; set them empty instead. |
| `properties[].options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `properties[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `properties[].options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `properties[].options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `properties[].options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `properties[].options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `properties[].options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `properties[].options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `properties[].options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `properties[].acl_enforcing_mode` | [`ACLEnforcingMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ACLEnforcingMode/index.md) | Which ACL the server starts from when it updates the permissions; see SetProperties `acl_mode`. `ACLENFORCING_MODE_DISALLOW_CHANGES` is rejected. Values: `ACLENFORCING_MODE_USE_PREVIOUS` (0), `ACLENFORCING_MODE_USE_PROVIDED` (1), `ACLENFORCING_MODE_RESET_TO_DEFAULT` (2), `ACLENFORCING_MODE_DISALLOW_CHANGES` (3). |
| `properties[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions to use with `ACLENFORCING_MODE_USE_PROVIDED`. Unset otherwise. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
## Response: SetPropertiesMultipleResponse
> Nested 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 [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The objects after the change, in the order of `properties`. |
| `results[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `results[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `results[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `results[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `results[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `results[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `results[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `results[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `results[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `results[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `results[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `results[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `results[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `results[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `results[].object_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 object (e.g. is the object deleted or a stub). |
| `results[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `results[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `results[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `results[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `results[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `results[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `results[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `results[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `results[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `results[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `results[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `results[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `results[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
---
# IRPCObjectOperations.AddObjectFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Adds new document file to a document.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddObjectFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object-file`
- **Request:** [`AddObjectFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md#request)
- **Response:** [`AddObjectFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Adds a file record to a checked-out object; the content is uploaded separately. On a checked-in
object the call fails with "The object is not checked out." The sequence that works:
1. [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md) the object.
2. AddObjectFile with the checked-out version: returns `file_ver`.
3. [UploadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md) with `upload_id: 0`, the object,
`file { file_ver, title, extension, size }` and the content, then
[UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md) with the returned
`upload_id` and the same `file`.
4. [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md).
A file whose content is never committed is dropped at check-in. To create a new document with
files, use
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) instead.
## Request: AddObjectFileRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The checked-out version, by number. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `title` | `string` | The file name without the extension. |
| `extension` | `string` | The file extension without the dot, for example `pdf`. |
| `created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The file's original creation time, if known. Optional. |
| `accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The file's last access time, if known. Optional. |
| `written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The file's last write time, if known. Optional. |
| `changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The file's last change time, if known. Optional. |
| `can_update_object_last_modified_timestamp` | `bool` | True to let the server update the object's Last modified timestamp from this change. |
## Response: AddObjectFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The new file's ID and version; pass it to UploadFile as `file.file_ver`. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `result` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The checked-out version after the operation, with its files. |
| `result.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `result.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `result.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `result.version_info.title` | `string` | The title (name) of the object in this version. |
| `result.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `result.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `result.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `result.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `result.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `result.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `result.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `result.version_info.class_id` | `int32` | The class ID of the version. |
| `result.version_info.version_guid` | `string` | The GUID of this version. |
| `result.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `result.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `result.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `result.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `result.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `result.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `result.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `result.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `result.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `result.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `result.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `result.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `result.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `result.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `result.object_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 object (e.g. is the object deleted or a stub). |
| `result.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `result.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `result.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `result.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `result.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `result.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md): Checks out one object.
- [UploadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md): Uploads a block of new content for an existing file of an object that is checked out to the caller.
- [UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md): Completes an upload made with UploadFile and stores it as the new content of the file.
- [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md): Checks in one object.
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
---
# IRPCObjectOperations.GetObjectHistory
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Lists the existing versions of an object, oldest first.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectHistory`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-history`
- **Request:** [`GetObjectHistoryRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/index.md#request)
- **Response:** [`GetObjectHistoryResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Each item is a specific version number. Versions that have been destroyed are not listed, so the
numbers can have gaps and the first one need not be 1. The version that is checked out to the
caller is included.
A caller who cannot read the object gets an empty list, not an error. A missing object gives "Not
found.". For version information per version, use
[GetObjectHistory2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory2/index.md).
## Request: GetObjectHistoryRequest
> Nested 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 object. |
| `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. |
## Response: GetObjectHistoryResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `versions[]` | repeated [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The versions, oldest first, as specific versions. |
| `versions[].type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `versions[].internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `versions[].external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `versions[].external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Related methods
- [GetObjectHistory2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory2/index.md): Lists the existing versions of an object with their version information, oldest first.
---
# IRPCObjectOperations.GetWorkflowStates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStates/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the states of the given workflow in the appropriate order.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetWorkflowStates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-workflow-states`
- **Request:** [`GetWorkflowStatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStates/index.md#request)
- **Response:** [`GetWorkflowStatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Returns the states of a workflow in their configured order. An unknown or hidden workflow returns
an empty list, not an error. The workflow IDs are in Workflow (38) values and in
[GetWorkflowsForClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/index.md).
`can_current_user_select` is computed against `current_state`: without it every state is
selectable. To change an object's state, set Workflow State (39) with
[SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md).
## Request: GetWorkflowStatesRequest
Request for getting workflow states.
> Nested 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_id` | `int32` | The workflow, the item ID of a Workflow (38) value. |
| `current_state` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The object's current state as a lookup value into value list 8 (states). Set it to get `can_current_user_select` for the transitions from this state; unset marks every state selectable. |
| `current_state.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `current_state.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `current_state.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. |
| `current_state.data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `current_state.data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `current_state.data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `current_state.data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `current_state.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. |
| `current_state.data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `current_state.data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `current_state.data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `current_state.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. |
| `current_state.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. |
| `current_state.data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `current_state.data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `current_state.data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `current_state.data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
| `obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object the states are for. Needed only when transition permissions depend on the object (`are_state_permissions_object_specific`). It does not replace `current_state`. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetWorkflowStatesResponse
Response for getting workflow states.
> Nested 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 [`StateBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateBasic/index.md) | States. |
| `results[].id` | `int32` | The state ID: the item ID of a Workflow State (39) value (value list 8). |
| `results[].name` | `string` | The name of the state. |
| `results[].can_current_user_select` | `bool` | True if the caller can move an object into this state from the `current_state` given in the request. Without `current_state`, every state is true. |
| `results[].are_state_permissions_object_specific` | `bool` | Specifies if the selectable flag is affected by pseudo users. If true, the selectable flag can be trusted only if the available state transitions are requested for a specific objver. |
| `results[].description` | `string` | The user description of the state. |
## Related methods
- [GetWorkflowsForClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/index.md): Gets all the workflows in a format suitable for client.
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
- [GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md): Gets the states and transitions of the given workflow.
---
# IRPCObjectOperations.GetWorkflowStatesAndTransitions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the states and transitions of the given workflow.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-workflow-states-and-transitions`
- **Request:** [`GetWorkflowStatesAndTransitionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md#request)
- **Response:** [`GetWorkflowStatesAndTransitionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Returns all states of the workflow and the transitions out of `current_state`. Without
`current_state`, `transitions` is empty, even if `obj_ver` is set. Each transition's
`id` can be set as State transition (99), a lookup into value list 17, with
[SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md); setting Workflow State (39) to
the target state works too. An unknown workflow returns empty lists.
Example from the Sample Vault: workflow 102 with `current_state` 108 returned all five states,
with the two reachable ones and the current one selectable, and the two transitions from state 108.
## Request: GetWorkflowStatesAndTransitionsRequest
Request for getting workflow states and transitions.
> Nested 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_id` | `int32` | The workflow, the item ID of a Workflow (38) value. |
| `current_state` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The object's current state as a lookup value into value list 8. Required to get any transitions. |
| `current_state.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `current_state.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `current_state.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. |
| `current_state.data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `current_state.data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `current_state.data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `current_state.data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `current_state.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. |
| `current_state.data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `current_state.data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `current_state.data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `current_state.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. |
| `current_state.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. |
| `current_state.data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `current_state.data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `current_state.data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `current_state.data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
| `obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object the transitions are for. Needed only when permissions depend on the object. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetWorkflowStatesAndTransitionsResponse
Request for getting workflow states and transitions.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `states[]` | repeated [`StateBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateBasic/index.md) | All states of the workflow, in order. |
| `states[].id` | `int32` | The state ID: the item ID of a Workflow State (39) value (value list 8). |
| `states[].name` | `string` | The name of the state. |
| `states[].can_current_user_select` | `bool` | True if the caller can move an object into this state from the `current_state` given in the request. Without `current_state`, every state is true. |
| `states[].are_state_permissions_object_specific` | `bool` | Specifies if the selectable flag is affected by pseudo users. If true, the selectable flag can be trusted only if the available state transitions are requested for a specific objver. |
| `states[].description` | `string` | The user description of the state. |
| `transitions[]` | repeated [`StateTransitionBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionBasic/index.md) | The transitions out of `current_state`; empty if it is unset. |
| `transitions[].id` | `int32` | The transition ID: the item ID of a State transition (99) value (value list 17). |
| `transitions[].name` | `string` | The name of the state transition. |
| `transitions[].from_state_id` | `int32` | From state ID. |
| `transitions[].to_state_id` | `int32` | To state ID. |
| `transitions[].can_current_user_select` | `bool` | True if the caller can use this transition. |
| `transitions[].are_state_transition_permissions_object_specific` | `bool` | Specifies if the selectable flag is affected by pseudo users. If true, the selectable flag can be trusted only if the available state transitions are requested for a specific objver. |
| `transitions[].description` | `string` | The client description of the state transition. |
## Related methods
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
- [GetWorkflowStates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStates/index.md): Gets the states of the given workflow in the appropriate order.
---
# IRPCObjectOperations.GetEffectivePermissions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetEffectivePermissions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the effective permissions of a document.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetEffectivePermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-effective-permissions`
- **Request:** [`GetEffectivePermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetEffectivePermissions/index.md#request)
- **Response:** [`GetEffectivePermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetEffectivePermissions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Lists every user of the vault who has any access to the object version through its ACL, with
their read, edit, delete and change-permissions access. Users without any access are left out, and
vault-level rights such as seeing all objects are not counted: an object with an empty ACL returns
an empty list even though administrators can see it. The caller must be able to read the
object.
## Request: GetEffectivePermissionsRequest
Requests effective permissions.
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version, by number. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetEffectivePermissionsResponse
Response for effective permissions 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 |
|---|---|---|
| `permissions[]` | repeated [`EffectivePermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EffectivePermissions/index.md) | One entry per user with any access, by user ID. |
| `permissions[].user_id` | `int32` | The user account ID. |
| `permissions[].permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | What the user can do with the object according to its ACL. |
| `permissions[].permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `permissions[].permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `permissions[].permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `permissions[].permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
---
# IRPCObjectOperations.RemoveObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Removes one object i.e. marks it deleted.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RemoveObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-object`
- **Request:** [`RemoveObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md#request)
- **Response:** [`RemoveObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Marks the object deleted; [UndeleteObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md)
restores it, [DestroyObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md) removes it for good.
A deleted object disappears from normal reads and searches: reading it as a normal user fails with
"Not found.", changing it fails with "The object has been removed. (ID: )", and deleting it
again fails the same way. Requires a license that allows modifications.
## Request: RemoveObjectRequest
> Nested 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 object to delete. |
| `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. |
## Response: RemoveObjectResponse
> Nested 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` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The object after the operation; `is_visible` is false for users who cannot see deleted objects. |
| `object.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object.object_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 object (e.g. is the object deleted or a stub). |
| `object.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `object.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `object.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [UndeleteObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md): Undeletes a previously removed object.
- [DestroyObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md): Permanently destroys an object, or one version of it.
- [RemoveObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjectFile/index.md): Removes a file from a document.
---
# IRPCObjectOperations.UndeleteObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Undeletes a previously removed object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UndeleteObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/undelete-object`
- **Request:** [`UndeleteObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md#request)
- **Response:** [`UndeleteObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Restores an object deleted with [RemoveObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md).
Requires the vault-level right to undelete objects (`undelete_objects`): a normal user gets "Access
denied." An object that is not deleted fails with "The object is not in deleted state."
## Request: UndeleteObjectRequest
> Nested 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 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. |
## Response: UndeleteObjectResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_object_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Information about the object after the operation. |
| `ext_object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_info.object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [RemoveObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md): Removes one object i.e. marks it deleted.
---
# IRPCObjectOperations.DestroyObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Permanently destroys an object, or one version of it.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DestroyObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/destroy-object`
- **Request:** [`DestroyObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md#request)
- **Response:** [`DestroyObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Destroying cannot be undone. Requires the vault-level right to destroy objects (`destroy_objects`):
a normal user gets "Access denied." The object does not need to be deleted first.
* Whole object: `all_versions: true` and `version.type: OBJ_VER_VERSION_TYPE_ALL`. Leaving
`version` unset fails with "The parameter is incorrect."
* One version: `all_versions: false` and `version` with `OBJ_VER_VERSION_TYPE_SPECIFIC` and the
number. The latest checked-in version cannot be destroyed: "Destroying the latest checked-in
version of an object is not allowed."
## Request: DestroyObjectRequest
> Nested 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 object. |
| `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. |
| `all_versions` | `bool` | True to destroy the whole object; false to destroy the version in `version`. |
| `version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | `OBJ_VER_VERSION_TYPE_ALL` when `all_versions` is true; otherwise the version number to destroy with `OBJ_VER_VERSION_TYPE_SPECIFIC`. |
| `version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: DestroyObjectResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [DestroyObjectVersions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersions/index.md): Permanently destroys specific object versions.
- [DestroyObjectVersionsByConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md): Destroys the old versions of an object that match search conditions, and returns how many were destroyed.
---
# IRPCObjectOperations.AddObjectWithFilesWithPropertyMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a new object with files, storing metadata about each property value (who or what set it,
why, and with what confidence).
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object-with-files-with-property-metadata`
- **Request:** [`AddObjectWithFilesWithPropertyMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/index.md#request)
- **Response:** [`AddObjectWithFilesWithPropertyMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFilesWithPropertyMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Behaves like [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) (the same
server implementation), with the same required properties, ACL and file sources.
Every value must carry `value_metadata` with a
numeric `confidence` string: a value without `value_metadata`, or with an empty `confidence`, fails
with "Type mismatch." Use `confidence: "0"` or `"-1"` when there is no confidence to
record; zero or less stores no confidence. Metadata whose fields are all empty or zero is not
stored. See [TypedValueMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md).
## Request: AddObjectWithFilesWithPropertyMetadataRequest
A request structure for the AddObjectWithFilesWithPropertyMetadata RPC call. Identical to
AddObjectWithFilesRequest except that properties carry per-value metadata (metametadata),
which is stored as OVPV_META rows alongside the object.
> 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 |
|---|---|---|
| `object_type_id` | `int32` | The object type of the new object. |
| `properties_with_metadata[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Property values of the new object, each with `value_metadata` (required, with a numeric `confidence`). |
| `properties_with_metadata[].property_def` | `int32` | Property definition ID. |
| `properties_with_metadata[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `properties_with_metadata[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `properties_with_metadata[].value.is_null_value` | `bool` | Is the value unset. |
| `properties_with_metadata[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `properties_with_metadata[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of the new object. Unset gives an empty ACL; see [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md). |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | If true, the object is checked in immediately, otherwise the object is left checked out. |
| `files` | [`ObjFileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSource/index.md) | File source. |
| `files.type` | [`ObjFileSourceType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjFileSourceType/index.md) | Which member of `data` is used. Must match the member that is set. Values: `OBJ_FILE_SOURCE_TYPE_UNDEFINED` (0), `OBJ_FILE_SOURCE_TYPE_BLANK_TEMPLATE` (1), `OBJ_FILE_SOURCE_TYPE_USER_DEFINED_TEMPLATE` (2), `OBJ_FILE_SOURCE_TYPE_UPLOADED_FILE` (3), `OBJ_FILE_SOURCE_TYPE_UPLOADED_FILES` (4), `OBJ_FILE_SOURCE_TYPE_EMPTY_FILES` (5), `OBJ_FILE_SOURCE_TYPE_FILE_CONTENT` (6). |
| `files.data` | [`ObjFileSourceUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md) | The source data; set the member that matches `type`. |
| `files.data.blank_template` | [`ObjFileSourceUnion.BlankTemplateData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-BlankTemplateData) (oneof data) | Blank template object file source. |
| `files.data.user_defined_template` | [`ObjFileSourceUnion.UserDefinedTemplateData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-UserDefinedTemplateData) (oneof data) | User defined template object file source. |
| `files.data.uploaded_file` | [`ObjFileSourceUnion.UploadedFileData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-UploadedFileData) (oneof data) | Uploaded object file source. |
| `files.data.uploaded_files` | [`ObjFileSourceUnion.UploadedFilesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-UploadedFilesData) (oneof data) | Uploaded object file source with multiple files. |
| `files.data.empty_files` | [`ObjFileSourceUnion.EmptyFilesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-EmptyFilesData) (oneof data) | Empty object file source (one or more files). Only the title and extension of each file are known; there is no upload id or size because the file contents have not been uploaded yet. This type may only be used when the object is created as a draft (the draft flag must be set); otherwise the request is rejected. |
| `files.data.file_content` | [`ObjFileSourceUnion.FileContentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileSourceUnion/index.md#t-FileContentData) (oneof data) | Inline file content object file source. |
| `draft` | `bool` | If true, the object is created checked out and flagged as a draft, allowing its file content to be uploaded later. Default false. |
## Response: AddObjectWithFilesWithPropertyMetadataResponse
A response structure for the AddObjectWithFilesWithPropertyMetadata RPC call. Same shape as
AddObjectWithFilesResponse.
> 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 |
|---|---|---|
| `is_visible_to_user` | `bool` | True if the latest version of the object is visible after the operation. |
| `created_object` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | If set (i.e. isVisibleToUser is true), the information, properties, and ACL of the latest version of the object after the operation. |
| `created_object.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `created_object.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `created_object.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `created_object.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `created_object.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `created_object.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `created_object.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_object.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `created_object.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `created_object.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `created_object.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `created_object.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
---
# IRPCObjectOperations.AddOrUpdateExternalObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddOrUpdateExternalObject/
Badges: `Vault API / core` `write` `session or assertion`
Creates, updates or deletes the object that mirrors an item of an external system, identified by
its external ID.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddOrUpdateExternalObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-or-update-external-object`
- **Request:** [`AddOrUpdateExternalObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddOrUpdateExternalObject/index.md#request)
- **Response:** [`AddOrUpdateExternalObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddOrUpdateExternalObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
With `deleted: true` the object is deleted instead; the deletion is not sent back to the external
system. Not available on servers where the feature is not enabled (fails with not implemented).
## Request: AddOrUpdateExternalObjectRequest
A structure that specifies add or update external object 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 |
|---|---|---|
| `ext_id` | `string` | The external ID of the object to update or create. |
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object ID of the object to update. Object type is required. Use id -1 if unknown, then extid is used. |
| `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. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties of the new object. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `deleted` | `bool` | True to delete the object identified by `ext_id` or `obj_id` instead of adding or updating it. The deletion is not sent back to the external system, where the change came from. |
## Response: AddOrUpdateExternalObjectResponse
A structure that specifies add or update external object response.
> 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 |
|---|---|---|
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties, and ACL of the latest version of the object after the operation. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
---
# IRPCObjectOperations.AddSingleFileDocument_SingleStep
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a single-file document from inline file content and checks it in. Older form; prefer
AddObjectWithFiles with an inline file source.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-single-file-document_-single-step`
- **Request:** [`AddSingleFileDocument_SingleStepRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep/index.md#request)
- **Response:** [`AddSingleFileDocument_SingleStepResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The document is always checked in. Single file (22) must be set to true in `properties`.
## Request: AddSingleFileDocument_SingleStepRequest
> 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_type` | `int32` | The object type of the new document. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties of the new document (represented by PropertyValue structs). |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The ACL for the new document. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `file_extension` | `string` | File extension, not including the dot ( e.g. "doc" ). |
| `creation_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `last_access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `last_write_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `change_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file_data` | `bytes` | File contents. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: AddSingleFileDocument_SingleStepResponse
> Nested 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_id` | `int32` | Receives the ID of the new document. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [AddSingleFileDocument_SingleStep2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2/index.md): Creates a single-file document from inline file content. Older form; prefer AddObjectWithFiles with an inline file source.
- [AddSingleFileDocument_SingleStep3](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3/index.md): Creates a single-file document from inline file content and returns its file version. Older form; prefer AddObjectWithFiles with an inline file source.
---
# IRPCObjectOperations.AddSingleFileDocument_SingleStep2
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a single-file document from inline file content. Older form; prefer AddObjectWithFiles
with an inline file source.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-single-file-document_-single-step2`
- **Request:** [`AddSingleFileDocument_SingleStep2Request`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2/index.md#request)
- **Response:** [`AddSingleFileDocument_SingleStep2Response`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Single file (22) must be set to true in `properties`. `check_in: false` is allowed only with
empty `file_data`; with content it fails with invalid argument.
## Request: AddSingleFileDocument_SingleStep2Request
> 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 |
|---|---|---|
| `object_type` | `int32` | The object type of the new document. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties of the new document (represented by PropertyValue structs). |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The ACL for the new document. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `file_extension` | `string` | File extension, not including the dot ( e.g. "doc" ). |
| `creation_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `last_access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `last_write_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `change_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file_data` | `bytes` | File contents. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | If true, the document is checked in immediately, otherwise the document is left to checked-out state. |
## Response: AddSingleFileDocument_SingleStep2Response
> 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 |
|---|---|---|
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties and ACL of the latest version of the new document, if `is_latest_visible` is true. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [AddSingleFileDocument_SingleStep](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep/index.md): Creates a single-file document from inline file content and checks it in. Older form; prefer AddObjectWithFiles with an inline file source.
- [AddSingleFileDocument_SingleStep3](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3/index.md): Creates a single-file document from inline file content and returns its file version. Older form; prefer AddObjectWithFiles with an inline file source.
---
# IRPCObjectOperations.AddSingleFileDocument_SingleStep3
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a single-file document from inline file content and returns its file version. Older
form; prefer AddObjectWithFiles with an inline file source.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-single-file-document_-single-step3`
- **Request:** [`AddSingleFileDocument_SingleStep3Request`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3/index.md#request)
- **Response:** [`AddSingleFileDocument_SingleStep3Response`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep3/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Single file (22) must be set to true in `properties`: without it the call fails with "The
mandatory property value "Single file" is missing." `check_in: false` is allowed only with empty
`file_data`; with content it fails with invalid argument. The file title is the
document's title.
## Request: AddSingleFileDocument_SingleStep3Request
> 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 |
|---|---|---|
| `object_type` | `int32` | The object type of the new document. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties of the new document (represented by PropertyValue structs). |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The ACL for the new document. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `file_extension` | `string` | File extension, not including the dot ( e.g. "doc" ). |
| `creation_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `last_access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `last_write_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `change_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file_data` | `bytes` | File contents. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | If true, the document is checked in immediately, otherwise the document is left to checked-out state. |
## Response: AddSingleFileDocument_SingleStep3Response
> 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 |
|---|---|---|
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties and ACL of the latest version of the new document, if `is_latest_visible` is true. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | Always receives the file version. (represented by FileVer struct.) |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [AddSingleFileDocument_SingleStep](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep/index.md): Creates a single-file document from inline file content and checks it in. Older form; prefer AddObjectWithFiles with an inline file source.
- [AddSingleFileDocument_SingleStep2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddSingleFileDocument_SingleStep2/index.md): Creates a single-file document from inline file content. Older form; prefer AddObjectWithFiles with an inline file source.
---
# IRPCObjectOperations.AddStubObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddStubObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a stub object that stands for an object in another vault. Used by replication and
cross-vault relationships; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddStubObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-stub-object`
- **Request:** [`AddStubObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddStubObject/index.md#request)
- **Response:** [`AddStubObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddStubObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: AddStubObjectRequest
> 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_type` | `int32` | The object type of the new object. |
| `explicit_object_id` | `int32` | The explicit internal ID of the new object if defined, -1 for automatic ID numbering. |
| `prop_vals[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties of the new object or empty if not specified. |
| `prop_vals[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `prop_vals[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `prop_vals[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `prop_vals[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `prop_vals[].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. |
| `utf8szacl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The ACL for the new object. |
| `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. |
| `objopflags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `objopflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `objopflags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `objopflags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `objopflags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `objopflags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `objopflags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `objopflags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `objopflags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | If true, the object is checked in immediately, otherwise the object is left to checked-out state. |
| `guid` | `string` | GUID for the stub object. |
## Response: AddStubObjectResponse
> 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 |
|---|---|---|
| `latest_visible` | `bool` | True if the latest version of the object is visible after the operation. |
| `latest` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties and ACL of the latest version of the object, if `latest_visible` is true. |
| `latest.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `latest.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `latest.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `latest.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `latest.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `latest.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `latest.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `latest.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. |
| `latest.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. |
| `latest.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. |
| `latest.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. |
| `latest.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. |
| `latest.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. |
| `latest.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `latest.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `latest.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `latest.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `latest.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.AddVersionTag
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddVersionTag/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Adds the specified tag to the document version. If the tag already exists in the
specified target version, this method does nothing. Other tags are not affected.
Optionally, this method can clear the specified tag from the other versions of
the target document.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/AddVersionTag`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-version-tag`
- **Request:** [`AddVersionTagRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddVersionTag/index.md#request)
- **Response:** [`AddVersionTagResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddVersionTag/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: AddVersionTagRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `tag` | `int32` | The ID of the version tag to add. |
| `clear_this_tag_from_other_versions` | `bool` | If true, this tag is cleared from the other versions of this document if it exists in them. |
## Response: AddVersionTagResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `modified_object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information of the modified document version after the operation. |
| `modified_object.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `modified_object.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `modified_object.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `modified_object.version_info.title` | `string` | The title (name) of the object in this version. |
| `modified_object.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `modified_object.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `modified_object.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `modified_object.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `modified_object.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `modified_object.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `modified_object.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `modified_object.version_info.class_id` | `int32` | The class ID of the version. |
| `modified_object.version_info.version_guid` | `string` | The GUID of this version. |
| `modified_object.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `modified_object.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `modified_object.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `modified_object.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `modified_object.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `modified_object.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `modified_object.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `modified_object.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `modified_object.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `modified_object.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `modified_object.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `modified_object.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `modified_object.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `modified_object.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `modified_object.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `modified_object.object_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 object (e.g. is the object deleted or a stub). |
| `modified_object.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `modified_object.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `modified_object.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `modified_object.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `modified_object.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `modified_object.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `modified_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Receives the property values of the modified document version after the operation. |
| `modified_properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `modified_properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `modified_properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `modified_properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `modified_properties[].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. |
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `latest_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The latest version of the object after the operation, if `is_latest_visible` is true. |
| `latest_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `latest_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `latest_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `latest_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `latest_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `latest_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `latest_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `latest_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `latest_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `latest_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `latest_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `latest_version.version_info.class_id` | `int32` | The class ID of the version. |
| `latest_version.version_info.version_guid` | `string` | The GUID of this version. |
| `latest_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `latest_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `latest_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `latest_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `latest_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `latest_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `latest_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `latest_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `latest_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `latest_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `latest_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `latest_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `latest_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `latest_version.object_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 object (e.g. is the object deleted or a stub). |
| `latest_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `latest_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `latest_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `latest_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.ChangeSecurity
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ChangeSecurity/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Changes the security settings of an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/ChangeSecurity`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-security`
- **Request:** [`ChangeSecurityRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ChangeSecurity/index.md#request)
- **Response:** [`ChangeSecurityResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ChangeSecurity/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Replaces the ACL of the object version in place: no check-out is needed and no new version is
created. `obj_ver` must name a version by number; the LATEST marker fails with "Not
found." Set `options.change_acl_in_all_versions` to change every version.
To give the object a named ACL, send that named ACL's `acl_for_objects` from
[GetNamedACLs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md), as for
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md).
The caller can remove their own access: the call succeeds and
`is_specified_version_still_visible` is false. Set
`options.require_read_access_after_operation` to prevent that: the call then fails with "The user
is about to lose the requested read access."
## Request: ChangeSecurityRequest
> 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version, by number. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The new ACL. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | `change_acl_in_all_versions` applies the ACL to every version; `require_read_access_after_operation` and the other `require_...` flags make the call fail if the caller would lose that access. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: ChangeSecurityResponse
> Nested 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_specified_version_still_visible` | `bool` | False if the caller can no longer see the version. |
| `specified_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Document info after this operation. |
| `specified_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `specified_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `specified_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `specified_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `specified_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `specified_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `specified_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `specified_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `specified_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `specified_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `specified_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `specified_version.version_info.class_id` | `int32` | The class ID of the version. |
| `specified_version.version_info.version_guid` | `string` | The GUID of this version. |
| `specified_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `specified_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `specified_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `specified_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `specified_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `specified_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `specified_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `specified_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `specified_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `specified_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `specified_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `specified_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `specified_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `specified_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `specified_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `specified_version.object_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 object (e.g. is the object deleted or a stub). |
| `specified_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `specified_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `specified_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `specified_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `specified_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `specified_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `result` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Information about the object after the operation. |
| `result.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `result.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `result.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `result.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `result.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `result.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `result.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `result.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `result.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `result.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `result.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `result.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `result.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `result.object_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 object (e.g. is the object deleted or a stub). |
| `result.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `result.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `result.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `result.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `result.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `result.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `result.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `result.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `result.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `result.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `result.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `result.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `result.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `result.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `result.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## 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.
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
---
# IRPCObjectOperations.CheckAccess
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckAccess/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Checks user's access to an object based on an ACL.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CheckAccess`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-access`
- **Request:** [`CheckAccessRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckAccess/index.md#request)
- **Response:** [`CheckAccessResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckAccess/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Evaluates an ACL for the caller without touching any object, for example a named ACL's
`acl_for_objects` before using it (for example, `has_access` true for "Full control for all internal
users", false for a named ACL of a group the user is not in).
## Request: CheckAccessRequest
> 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 |
|---|---|---|
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The object's ACL. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `required_access` | [`ObjectAccess`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectAccess/index.md) | The object-level access requirements that must be fulfilled. |
| `required_access.all` | `bool` | Specifies all flags set; Including any future flags. |
| `required_access.read` | `bool` | Read. |
| `required_access.edit` | `bool` | Edit. |
| `required_access.change_permissions` | `bool` | Change security settings. |
| `required_access.delete_object` | `bool` | Delete. |
| `required_access.attach_objects` | `bool` | Attach objects. |
## Response: CheckAccessResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `has_access` | `bool` | Receives true if the user has the required access based on the given ACL. |
---
# IRPCObjectOperations.CheckInExternalChanges
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInExternalChanges/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates new versions of objects whose files were changed in an external editing system
(SharePoint Embedded co-authoring). No version is created for an object without changes.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CheckInExternalChanges`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-in-external-changes`
- **Request:** [`CheckInExternalChangesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInExternalChanges/index.md#request)
- **Response:** [`CheckInExternalChangesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInExternalChanges/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients with SharePoint Embedded storage.
## Request: CheckInExternalChangesRequest
A structure that specifies check in external changes 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 |
|---|---|---|
| `obj_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | An array of ObjIDs. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Response: CheckInExternalChangesResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Array contains object information for latest checked in version after operation. New object version is not created, if no changes are detected. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `object_results[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Array contains object results for the checked in objects after the operation. |
| `object_results[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object_results[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object_results[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_results[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_results[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_results[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_results[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_results[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_results[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_results[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_results[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_results[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_results[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_results[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_results[].object_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 object (e.g. is the object deleted or a stub). |
| `object_results[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_results[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_results[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_results[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_results[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_results[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `object_results[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object_results[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object_results[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_results[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_results[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_results[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_results[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object_results[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `object_results[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
## Related methods
- [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md): Checks in one object.
---
# IRPCObjectOperations.CheckInMultiple
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInMultiple/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Checks in several objects in one call.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CheckInMultiple`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-in-multiple`
- **Request:** [`CheckInMultipleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInMultiple/index.md#request)
- **Response:** [`CheckInMultipleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckInMultiple/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Each object behaves as in [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md): `obj_vers` must
name the checked-out versions by number. The same `properties` are set on every object before
check-in.
## Request: CheckInMultipleRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object versions. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The properties to add/replace. (represented by PropertyValueArray array ) |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: CheckInMultipleResponse
> Nested 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 [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `results[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `results[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `results[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `results[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `results[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `results[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `results[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `results[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `results[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `results[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `results[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `results[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `results[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `results[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `results[].object_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 object (e.g. is the object deleted or a stub). |
| `results[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `results[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `results[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `results[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `results[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `results[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `results[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `results[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `results[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `results[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `results[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `results[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `results[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md): Checks in one object.
---
# IRPCObjectOperations.CheckOutMultiple
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOutMultiple/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Checks out several objects in one call.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CheckOutMultiple`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-out-multiple`
- **Request:** [`CheckOutMultipleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOutMultiple/index.md#request)
- **Response:** [`CheckOutMultipleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOutMultiple/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Each object behaves as in [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md).
`checked_out_versions` and `previous_versions` are in the order of `obj_ids`.
## Request: CheckOutMultipleRequest
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Objects. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Response: CheckOutMultipleResponse
> 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 |
|---|---|---|
| `checked_out_versions[]` | repeated [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | Results. |
| `checked_out_versions[].object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `checked_out_versions[].object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `checked_out_versions[].object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `checked_out_versions[].properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `checked_out_versions[].properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `checked_out_versions[].properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `checked_out_versions[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `checked_out_versions[].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. |
| `checked_out_versions[].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. |
| `checked_out_versions[].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. |
| `checked_out_versions[].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. |
| `checked_out_versions[].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. |
| `checked_out_versions[].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. |
| `checked_out_versions[].current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `checked_out_versions[].current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `checked_out_versions[].current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `checked_out_versions[].current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `checked_out_versions[].current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `previous_versions[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Results. |
| `previous_versions[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `previous_versions[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `previous_versions[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `previous_versions[].version_info.title` | `string` | The title (name) of the object in this version. |
| `previous_versions[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `previous_versions[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `previous_versions[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `previous_versions[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `previous_versions[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `previous_versions[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `previous_versions[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `previous_versions[].version_info.class_id` | `int32` | The class ID of the version. |
| `previous_versions[].version_info.version_guid` | `string` | The GUID of this version. |
| `previous_versions[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `previous_versions[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `previous_versions[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `previous_versions[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `previous_versions[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `previous_versions[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `previous_versions[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `previous_versions[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `previous_versions[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `previous_versions[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `previous_versions[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `previous_versions[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `previous_versions[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `previous_versions[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `previous_versions[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `previous_versions[].object_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 object (e.g. is the object deleted or a stub). |
| `previous_versions[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `previous_versions[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `previous_versions[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `previous_versions[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `previous_versions[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `previous_versions[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [CheckOut](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckOut/index.md): Checks out one object.
---
# IRPCObjectOperations.ConvertToPDF
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ConvertToPDF/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Converts the specified object file to PDF format.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/ConvertToPDF`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/convert-to-pdf`
- **Request:** [`ConvertToPDFRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ConvertToPDF/index.md#request)
- **Response:** [`ConvertToPDFResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ConvertToPDF/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The object must be checked out to the caller; on a checked-in object the call fails with "The
object is not checked out." With `leave_original`, the PDF is added as a separate file;
on a single-file document this turns the document into a multi-file document. Without
it, the file is replaced by the PDF. Check the object in afterwards.
## Request: ConvertToPDFRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The file version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file id. If the file id part is empty / -1 then all files of the object version are converted. |
| `file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_id.internal_id` | `int32` | The file ID. |
| `file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `leave_original` | `bool` | True if the resulting PDF file should be stored as a separate file, with the same title as the original file but with the .pdf extension. |
| `overwrite` | `bool` | True if overwriting an existing target file with the same name is allowed. Effective only if bStoreAsSeparateFile is true. |
| `pdfa1b` | `bool` | True if the resulting PDF file should comply with the PDF/A-1b standard. |
| `fail_on_unsupported` | `bool` | If true, the operation fails if the source file is in unsupported format. If false, the operation silently skips unsupported source files. |
## Response: ConvertToPDFResponse
> Nested 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_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The checked-out version after the conversion. |
| `object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_version.version_info.class_id` | `int32` | The class ID of the version. |
| `object_version.version_info.version_guid` | `string` | The GUID of this version. |
| `object_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_version.object_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 object (e.g. is the object deleted or a stub). |
| `object_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `success` | `bool` | Receives true if the conversion from the source file format (based on the extension and actual content format detection) is supported. If false, the conversion is not supported and the caller should not attempt to use the target file. |
| `files[]` | repeated [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | Receives an array of file versions of the PDF files in the object version. |
| `files[].file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `files[].file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `files[].file_id.internal_id` | `int32` | The file ID. |
| `files[].file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `files[].type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `files[].internal_version` | `int32` | The file version number. |
| `files[].external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `files[].external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.CopyConflictObjectAsNewVersionToBaseObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CopyConflictObjectAsNewVersionToBaseObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Resolves a replication conflict by adding the conflict object's content as a new version of the
base object. Used by M-Files clients; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CopyConflictObjectAsNewVersionToBaseObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/copy-conflict-object-as-new-version-to-base-object`
- **Request:** [`CopyConflictObjectAsNewVersionToBaseObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CopyConflictObjectAsNewVersionToBaseObject/index.md#request)
- **Response:** [`CopyConflictObjectAsNewVersionToBaseObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CopyConflictObjectAsNewVersionToBaseObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: CopyConflictObjectAsNewVersionToBaseObjectRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `base_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The latest base object versiuon on which the new version is created. (represented by ObjVer struct.) |
| `base_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `base_obj_ver.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). |
| `base_obj_ver.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`. |
| `base_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `base_obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `base_obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `base_obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `base_obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `conflict_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The related conflict object latest version. Can be a deleted object. (represented by ObjVer struct.) |
| `conflict_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `conflict_obj_ver.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). |
| `conflict_obj_ver.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`. |
| `conflict_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `conflict_obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `conflict_obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `conflict_obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `conflict_obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: CopyConflictObjectAsNewVersionToBaseObjectResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_object_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Information about the object after the operation. |
| `ext_object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_info.object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.CountObjectVersionsMatchingConditions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Counts the versions of an object that DestroyObjectVersionsByConditions would destroy with the
same inputs, without destroying anything.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/count-object-versions-matching-conditions`
- **Request:** [`CountObjectVersionsMatchingConditionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions/index.md#request)
- **Response:** [`CountObjectVersionsMatchingConditionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Uses the same selection and the same rules for kept versions as
[DestroyObjectVersionsByConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md).
Requires the vault-level right to destroy objects.
## Request: CountObjectVersionsMatchingConditionsRequest
The request of CountObjectVersionsMatchingConditions. It has the same fields as
DestroyObjectVersionsByConditionsRequest.
> Nested 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 object whose versions are counted. |
| `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. |
| `conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions a version must match to be destroyed. Must not be empty. |
| `conditions[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `conditions[].expression.type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `conditions[].expression.data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `conditions[].expression.indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `conditions[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `conditions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `conditions[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `conditions[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `conditions[].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. |
## Response: CountObjectVersionsMatchingConditionsResponse
The response of CountObjectVersionsMatchingConditions: the number of versions that
DestroyObjectVersionsByConditions would destroy with the same inputs. Nothing is destroyed.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `matching_version_count` | `int32` | The number of versions that would be destroyed. |
## Related methods
- [DestroyObjectVersionsByConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md): Destroys the old versions of an object that match search conditions, and returns how many were destroyed.
---
# IRPCObjectOperations.CreateNewObjectWithPropertyMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CreateNewObjectWithPropertyMetadata/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Creates a new object without files, storing metadata about each property value.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/CreateNewObjectWithPropertyMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-new-object-with-property-metadata`
- **Request:** [`CreateNewObjectWithPropertyMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CreateNewObjectWithPropertyMetadata/index.md#request)
- **Response:** [`CreateNewObjectWithPropertyMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CreateNewObjectWithPropertyMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Every value must carry `value_metadata` with a numeric `confidence` string (for example `"0"`);
otherwise the call fails with "Type mismatch." The required properties and the `acl`
pitfall are the same as for
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md).
## Request: CreateNewObjectWithPropertyMetadataRequest
A request structure for the CreateNewObjectWithPropertyMetadata RPC call. Creates a new
object in a single call, storing the property-related metadata (metametadata) carried
alongside each property value in addition to the value itself.
> 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 |
|---|---|---|
| `object_type_id` | `int32` | The object type of the new object. |
| `properties_with_metadata[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Property values of the new object, each with `value_metadata` (required, with a numeric `confidence`). |
| `properties_with_metadata[].property_def` | `int32` | Property definition ID. |
| `properties_with_metadata[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `properties_with_metadata[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `properties_with_metadata[].value.is_null_value` | `bool` | Is the value unset. |
| `properties_with_metadata[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `properties_with_metadata[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of the new object. Unset gives an empty ACL; see [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md). |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `check_in` | `bool` | If true, the object is checked in immediately, otherwise the object is left checked out. |
| `allow_missing_required_properties` | `bool` | If true, the object can be created with missing required properties. |
## Response: CreateNewObjectWithPropertyMetadataResponse
A response structure for the CreateNewObjectWithPropertyMetadata RPC call.
> 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 |
|---|---|---|
| `is_visible_to_user` | `bool` | True if the latest version of the object is visible after the operation. |
| `created_object` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | If set (i.e. isVisibleToUser is true), the information, properties, and ACL of the latest version of the object after the operation. |
| `created_object.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `created_object.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `created_object.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `created_object.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `created_object.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `created_object.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `created_object.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_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. |
| `created_object.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `created_object.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `created_object.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `created_object.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `created_object.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
## Related methods
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
---
# IRPCObjectOperations.DemoteObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DemoteObjects/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Removes the M-Files metadata from promoted objects, turning them back into unmanaged objects of
their external repository.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DemoteObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/demote-objects`
- **Request:** [`DemoteObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DemoteObjects/index.md#request)
- **Response:** [`DemoteObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DemoteObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Requires the vault-level right to destroy objects.
## Request: DemoteObjectsRequest
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Objects. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Response: DemoteObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_object_infos[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `ext_object_infos[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_infos[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_infos[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_infos[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_infos[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_infos[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_infos[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_infos[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_infos[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_infos[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_infos[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_infos[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_infos[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_infos[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_infos[].object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_infos[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_infos[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_infos[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_infos[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_infos[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_infos[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_infos[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_infos[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_infos[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_infos[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_infos[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_infos[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_infos[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
---
# IRPCObjectOperations.DestroyObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjects/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Permanently destroys several objects with all their versions. Requires the vault-level right to
destroy objects.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DestroyObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/destroy-objects`
- **Request:** [`DestroyObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjects/index.md#request)
- **Response:** [`DestroyObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: DestroyObjectsRequest
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Objects. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Response: DestroyObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.DestroyObjectVersions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersions/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Permanently destroys specific object versions.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DestroyObjectVersions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/destroy-object-versions`
- **Request:** [`DestroyObjectVersionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersions/index.md#request)
- **Response:** [`DestroyObjectVersionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Each entry must name a version by number; the LATEST marker fails with "The parameter is
incorrect." The latest checked-in version cannot be destroyed. The call is all or nothing: if one
version cannot be destroyed (for example it no longer exists), none is. Requires the
vault-level right to destroy objects.
## Request: DestroyObjectVersionsRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Objects. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: DestroyObjectVersionsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [DestroyObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md): Permanently destroys an object, or one version of it.
- [DestroyObjectVersionsByConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md): Destroys the old versions of an object that match search conditions, and returns how many were destroyed.
---
# IRPCObjectOperations.DestroyObjectVersionsByConditions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Destroys the old versions of an object that match search conditions, and returns how many were
destroyed.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/destroy-object-versions-by-conditions`
- **Request:** [`DestroyObjectVersionsByConditionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md#request)
- **Response:** [`DestroyObjectVersionsByConditionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The newest version is never destroyed, and when the object is checked out both the checked-out
version and the latest checked-in version are kept, whoever has the object checked out; conditions
cannot override this. `conditions` must not be empty. Check a condition set first with
[CountObjectVersionsMatchingConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions/index.md):
destruction cannot be undone. If `more_versions_remain` is true, call again. Requires the
vault-level right to destroy objects. Not available on servers where the feature is not enabled
(the call fails with not implemented).
## Request: DestroyObjectVersionsByConditionsRequest
The request of DestroyObjectVersionsByConditions: the object and the conditions a version must
match to be destroyed. The conditions only select candidates: the newest version, and for a
checked-out object the checked-out version and the latest checked-in version, are always kept.
> Nested 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 object whose versions are destroyed. |
| `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. |
| `conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions a version must match to be destroyed. Must not be empty. |
| `conditions[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `conditions[].expression.type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `conditions[].expression.data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `conditions[].expression.indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `conditions[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `conditions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `conditions[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `conditions[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `conditions[].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. |
| `max_versions_to_destroy` | `int32` | The most versions this call destroys. Zero or less means no limit, so set a limit deliberately. |
## Response: DestroyObjectVersionsByConditionsResponse
The response of DestroyObjectVersionsByConditions: the number of versions destroyed, and whether
more matching versions remain.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `destroyed_version_count` | `int32` | The number of versions destroyed by this call. |
| `more_versions_remain` | `bool` | True if more matching versions remained; call again to continue. |
## Related methods
- [CountObjectVersionsMatchingConditions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CountObjectVersionsMatchingConditions/index.md): Counts the versions of an object that DestroyObjectVersionsByConditions would destroy with the same inputs, without destroying anything.
- [DestroyObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObject/index.md): Permanently destroys an object, or one version of it.
- [DestroyObjectVersions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DestroyObjectVersions/index.md): Permanently destroys specific object versions.
---
# IRPCObjectOperations.DetectTextLanguage
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DetectTextLanguage/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Detects the language of a plain text.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DetectTextLanguage`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/detect-text-language`
- **Request:** [`DetectTextLanguageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DetectTextLanguage/index.md#request)
- **Response:** [`DetectTextLanguageResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DetectTextLanguage/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: DetectTextLanguageRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `text_content` | `string` | The plain text input. |
## Response: DetectTextLanguageResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `language_detection_result` | [`LanguageDetectionResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LanguageDetectionResult/index.md) | Structure containing the language and detection confidence. |
| `language_detection_result.language` | `string` | The detected language specified by ISO 639-1 Language Code. |
| `language_detection_result.confidence` | `uint32` | The confidence of the detected language which represents a percentage. |
---
# IRPCObjectOperations.DownloadFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/
Badges: `Vault API / core` `write` `session or assertion`
Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP
gateway.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-file`
- **Request:** [`DownloadFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md#request)
- **Response:** [`DownloadFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
To download a file over gRPC, use
[DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md) and
[DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md).
## Request: DownloadFileRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID. |
| `file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_id.internal_id` | `int32` | The file ID. |
| `file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `format` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | Specifies the file format to download. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
## Response: DownloadFileResponse
No fields.
## Related methods
- [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md): Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum.
- [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md): Reads a block of a file from a download session.
- [DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md): Closes a download session.
- [DownloadFileWithDownloadID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadID/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
- [DownloadFileWithDownloadKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadKey/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.DownloadFileWithDownloadID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadID/
Badges: `Vault API / core` `write` `session or assertion`
Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP
gateway.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadFileWithDownloadID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-file-with-download-id`
- **Request:** [`DownloadFileWithDownloadIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadID/index.md#request)
- **Response:** [`DownloadFileWithDownloadIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadID/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: DownloadFileWithDownloadIDRequest
> Nested 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` | Download session identifier. |
| `content_disposition_inline` | `bool` | True if the content is expected to be displayed inline in the browser. |
## Response: DownloadFileWithDownloadIDResponse
No fields.
## Related methods
- [DownloadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.DownloadFileWithDownloadKey
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadKey/
Badges: `Vault API / core` `write` `session or assertion`
Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP
gateway.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadFileWithDownloadKey`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-file-with-download-key`
- **Request:** [`DownloadFileWithDownloadKeyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadKey/index.md#request)
- **Response:** [`DownloadFileWithDownloadKeyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFileWithDownloadKey/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: DownloadFileWithDownloadKeyRequest
> Nested 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_key` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | Contains identifier that will be used to locate the file. |
| `download_key.value` | `string` | String. |
| `format` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | Specifies the file format to download. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
| `content_disposition_inline` | `bool` | True if the content is expected to be displayed inline in the browser. |
| `need_checksum` | `bool` | True if the caller wants to receive the checksum of the file. Will be returned in the response headers. |
## Response: DownloadFileWithDownloadKeyResponse
No fields.
## Related methods
- [DownloadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.DownloadTempFileFromUpload_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Opens a download session for a committed upload, to read it back or as a PDF, without creating
an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-temp-file-from-upload_-begin`
- **Request:** [`DownloadTempFileFromUpload_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md#request)
- **Response:** [`DownloadTempFileFromUpload_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Pass the `upload_id` of an upload committed with
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md); an uncommitted
upload fails. Read the content with
[DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md).
`FILE_FORMAT_PDF` returns a PDF rendition of the upload (for example to preview a document before
it is created); `file_extension` is then "pdf". The download session ends with the upload.
## Request: DownloadTempFileFromUpload_BeginRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The ID of a committed upload. 0 if `file_ref` is set. |
| `file_format` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | `FILE_FORMAT_NATIVE` (default) or `FILE_FORMAT_PDF`. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
| `file_ref` | `string` | The `file_ref` of an upload completed with `FileUploadEnd`, instead of `upload_id`. Set exactly one of the two. |
| `extension` | `string` | The file name extension, without the dot. Used only with `file_ref`. |
## Response: DownloadTempFileFromUpload_BeginResponse
> Nested 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 for `DownloadFile_ReadBlock`. |
| `file_size` | `int64` | The size of the content to download, in bytes. |
| `file_extension` | `string` | The extension of the content to download; empty if the upload has none. |
## Related methods
- [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.
- [DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md): Reads a block of a file from a download session.
---
# IRPCObjectOperations.FindEmailDuplicates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindEmailDuplicates/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Finds duplicate email objects in the vault.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/FindEmailDuplicates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/find-email-duplicates`
- **Request:** [`FindEmailDuplicatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindEmailDuplicates/index.md#request)
- **Response:** [`FindEmailDuplicatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindEmailDuplicates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: FindEmailDuplicatesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `message_id` | `string` | The message ID. |
## Response: FindEmailDuplicatesResponse
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Results. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
---
# IRPCObjectOperations.FindFileDuplicates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicates/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Finds files in the vault with the same content as the given file version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/FindFileDuplicates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/find-file-duplicates`
- **Request:** [`FindFileDuplicatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicates/index.md#request)
- **Response:** [`FindFileDuplicatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: FindFileDuplicatesRequest
> Nested 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_file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The obj file version. |
| `obj_file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver.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_file_ver.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_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `include_versions_of_this_file` | `bool` | True if the results should include duplicates which are other versions of the same file. |
| `exclude_files_from_deleted_objects` | `bool` | True if the results should exclude duplicates which belong to deleted objects. |
## Response: FindFileDuplicatesResponse
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Results. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Related methods
- [FindFileDuplicatesOfObjVer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicatesOfObjVer/index.md): Finds files in the vault with the same content as the files of the given object version.
---
# IRPCObjectOperations.FindFileDuplicatesOfObjVer
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicatesOfObjVer/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Finds files in the vault with the same content as the files of the given object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/FindFileDuplicatesOfObjVer`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/find-file-duplicates-of-obj-ver`
- **Request:** [`FindFileDuplicatesOfObjVerRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicatesOfObjVer/index.md#request)
- **Response:** [`FindFileDuplicatesOfObjVerResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicatesOfObjVer/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: FindFileDuplicatesOfObjVerRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The obj version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `exclude_files_from_deleted_objects` | `bool` | True if the results should exclude duplicates which belong to deleted objects. |
## Response: FindFileDuplicatesOfObjVerResponse
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Results. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Related methods
- [FindFileDuplicates](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFileDuplicates/index.md): Finds files in the vault with the same content as the given file version.
---
# IRPCObjectOperations.FindFilesByChecksum
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFilesByChecksum/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Finds file versions in the vault by MD5 checksum.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/FindFilesByChecksum`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/find-files-by-checksum`
- **Request:** [`FindFilesByChecksumRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFilesByChecksum/index.md#request)
- **Response:** [`FindFilesByChecksumResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindFilesByChecksum/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: FindFilesByChecksumRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `low_digest` | `int64` | Specifies the low-order part of the MD5 checksum. |
| `high_digest` | `int64` | Specifies the high-order part of the MD5 checksum. |
| `exclude_files_from_deleted_objects` | `bool` | True if the results should exclude duplicates which belong to deleted objects. |
## Response: FindFilesByChecksumResponse
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Results. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
---
# IRPCObjectOperations.FindVaultDuplicates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindVaultDuplicates/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Finds all groups of duplicate files in the vault.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/FindVaultDuplicates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/find-vault-duplicates`
- **Request:** [`FindVaultDuplicatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindVaultDuplicates/index.md#request)
- **Response:** [`FindVaultDuplicatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FindVaultDuplicates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: FindVaultDuplicatesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `exclude_files_from_deleted_objects` | `bool` | True if the results should exclude duplicates which belong to deleted objects. |
## Response: FindVaultDuplicatesResponse
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Results. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
---
# IRPCObjectOperations.FollowObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FollowObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Starts or stops following the specified object. While the object is being followed, the current user will be notified if the object changes.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/FollowObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/follow-object`
- **Request:** [`FollowObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FollowObject/index.md#request)
- **Response:** [`FollowObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FollowObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Starts (`follow_state: true`) or stops (`false`) following the object for the caller.
## Request: FollowObjectRequest
> Nested 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 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. |
| `follow_state` | `bool` | True if the objects should be followed, false if not followed. |
## Response: FollowObjectResponse
No fields.
---
# IRPCObjectOperations.GetAutomaticMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetAutomaticMetadata/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets automatic metadata from the vault's metadata providers, for an object about to be created
(from its uploaded files) or for an existing object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetAutomaticMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-automatic-metadata`
- **Request:** [`GetAutomaticMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetAutomaticMetadata/index.md#request)
- **Response:** [`GetAutomaticMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetAutomaticMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetAutomaticMetadataRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `request` | [`AutomaticMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticMetadataRequest/index.md) | The automatic metadata extraction request. |
| `request.upload_ids[]` | repeated `int32` | The upload session IDs associated with the metadata request. If the metadata request is pointed for existing object, the existing files are used instead. |
| `request.object_type_id` | `int32` | The object type of object that is about to be created. |
| `request.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version if the automatic metadata request is pointed for existing object. |
| `request.obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `request.obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `request.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The property values of the object. |
| `request.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `request.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `request.services[]` | repeated `string` | List of requested metadata providers. Empty if all metadata providers are applied. |
| `request.custom_data` | `string` | The custom data for metadata providers. |
| `request.uploaded_files[]` | repeated [`UploadedFile`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UploadedFile/index.md) | Files of stateless uploads (fileRef, title and extension) used like the upload session IDs. Only uploaded files with a file_ref are accepted. |
| `request.uploaded_files[].upload_id` | `int32` | The upload session ID from UploadTempFile, committed with UploadTempFileCommit. Zero if `file_ref` is set. |
| `request.uploaded_files[].title` | `string` | The title of the file. |
| `request.uploaded_files[].extension` | `string` | File extension, not including the dot (e.g. "doc"). |
| `request.uploaded_files[].size` | `int64` | The logical size of the file in bytes. |
| `request.uploaded_files[].file_ref` | `string` | The `file_ref` of a stateless upload (FileUploadWhole or FileUploadEnd). Empty if `upload_id` is set. Exactly one of `upload_id` and `file_ref` must be set. |
## Response: GetAutomaticMetadataResponse
> 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 |
|---|---|---|
| `response` | [`AutomaticMetadataResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticMetadataResult/index.md) | Receives the automatic metadata. |
| `response.property_value_suggestions[]` | repeated [`PropertyValueSuggestion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueSuggestion/index.md) | Property value suggestions. |
| `response.property_value_suggestions[].property_definition_id` | `int32` | The property definition ID. |
| `response.property_value_suggestions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The typed value. |
| `response.property_value_suggestions[].display_value` | `string` | Display value for the suggestion. Can be empty. |
| `response.property_value_suggestions[].confidence` | `float` | The projected quality of the suggestion. |
| `response.property_value_suggestions[].is_fact` | `bool` | True if the suggestion is a fact (i.e. known to be valid for sure). |
| `response.property_value_suggestions[].is_new_value_list_item` | `bool` | True if the suggestion depicts a new value for value lists. |
| `response.property_value_suggestions[].new_value_list_item_property_suggestions[]` | repeated [`PropertyValueSuggestion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueSuggestion/index.md) (recursive) | Suggestions that should be used when new object is created with this suggestion. |
| `response.property_value_suggestions[].reason` | `string` | Rationale explaining why the suggestion is being made. Can be empty. |
| `response.property_value_suggestions[].suggested_name` | `string` | Display name of a not-yet-created property (discovery-origin only). Empty otherwise. |
| `response.property_value_suggestions[].suggested_data_type` | `int32` | MFDataType of the suggested new property (discovery-origin only). Zero otherwise. |
| `response.property_value_suggestions[].instruction` | `string` | LLM-authored extraction instruction for a discovery-origin property. Empty otherwise. |
---
# IRPCObjectOperations.GetComparisonUrlOfUploadedFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetComparisonUrlOfUploadedFile/
Badges: `Vault API / core` `write` `session or assertion`
Gets a URL of a page that shows the differences between a document file in the vault and a
stateless upload identified by its `file_ref`.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetComparisonUrlOfUploadedFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-comparison-url-of-uploaded-file`
- **Request:** [`GetComparisonUrlOfUploadedFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetComparisonUrlOfUploadedFile/index.md#request)
- **Response:** [`GetComparisonUrlOfUploadedFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetComparisonUrlOfUploadedFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Fails with not implemented on servers that do not support stateless uploads.
## Request: GetComparisonUrlOfUploadedFileRequest
> Nested 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_file_ver_original` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and file version to compare. |
| `obj_file_ver_original.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver_original.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_file_ver_original.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_file_ver_original.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver_original.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver_original.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver_original.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver_original.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver_original.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file_ref` | `string` | The file_ref of a stateless upload ended with FileUploadEnd, to compare with. |
| `file_name` | `string` | The file name of the uploaded file to display in the compare UI. Must include the extension, as a file_ref has no file name. |
| `language` | `string` | The language to use for localization of the compare UI. |
| `allow_download` | `bool` | True if the download options should be enabled in the compare UI, false otherwise. |
## Response: GetComparisonUrlOfUploadedFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `compare_url` | `string` | The document comparison URL. |
---
# IRPCObjectOperations.GetDocEventSubscriptions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocEventSubscriptions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the caller's event subscriptions for an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetDocEventSubscriptions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-doc-event-subscriptions`
- **Request:** [`GetDocEventSubscriptionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocEventSubscriptions/index.md#request)
- **Response:** [`GetDocEventSubscriptionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocEventSubscriptions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetDocEventSubscriptionsRequest
> Nested 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 object ID. (represented by ObjID struct.) |
| `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. |
## Response: GetDocEventSubscriptionsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `subscriptions[]` | repeated [`EventSubscription`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventSubscription/index.md) | Receives the results. |
| `subscriptions[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. [ switch_is( eventtype ) ] EventTypeSpecificDataUnion etsdu; //!< Additional event type -specific data as a union. |
---
# IRPCObjectOperations.GetDocumentComparisonEnabled
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonEnabled/
Badges: `Vault API / core` `write` `session or assertion`
Tells whether document comparison is available in the vault.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetDocumentComparisonEnabled`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-document-comparison-enabled`
- **Request:** [`GetDocumentComparisonEnabledRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonEnabled/index.md#request)
- **Response:** [`GetDocumentComparisonEnabledResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonEnabled/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetDocumentComparisonEnabledRequest
No fields.
## Response: GetDocumentComparisonEnabledResponse
> Nested 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` | Receives true if the document comparison feature is enabled. |
---
# IRPCObjectOperations.GetDocumentComparisonUrl
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonUrl/
Badges: `Vault API / core` `write` `session or assertion`
Gets a URL of a page that shows the differences between two document files in the vault.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetDocumentComparisonUrl`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-document-comparison-url`
- **Request:** [`GetDocumentComparisonUrlRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonUrl/index.md#request)
- **Response:** [`GetDocumentComparisonUrlResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonUrl/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetDocumentComparisonUrlRequest
> Nested 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_file_ver_original` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and file version to compare. |
| `obj_file_ver_original.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver_original.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_file_ver_original.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_file_ver_original.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver_original.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver_original.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver_original.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver_original.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver_original.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `obj_file_ver_modified` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and file version to compare with. |
| `obj_file_ver_modified.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver_modified.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_file_ver_modified.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_file_ver_modified.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver_modified.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver_modified.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver_modified.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver_modified.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver_modified.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `language` | `string` | The language to use for localization of the compare UI. |
| `allow_download` | `bool` | True if the download options should be enabled in the compare UI, false otherwise. |
## Response: GetDocumentComparisonUrlResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `compare_url` | `string` | Receives the document comparison URL. |
---
# IRPCObjectOperations.GetDocumentComparisonWithTempFileUrl
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonWithTempFileUrl/
Badges: `Vault API / core` `write` `session or assertion`
Gets a URL of a page that shows the differences between a document file in the vault and an
uploaded temporary file.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetDocumentComparisonWithTempFileUrl`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-document-comparison-with-temp-file-url`
- **Request:** [`GetDocumentComparisonWithTempFileUrlRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonWithTempFileUrl/index.md#request)
- **Response:** [`GetDocumentComparisonWithTempFileUrlResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetDocumentComparisonWithTempFileUrl/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetDocumentComparisonWithTempFileUrlRequest
> Nested 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_file_ver_original` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and file version to compare. |
| `obj_file_ver_original.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver_original.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_file_ver_original.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_file_ver_original.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver_original.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver_original.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver_original.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver_original.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver_original.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `upload_session_id` | `int32` | Upload session ID. |
| `upload_file_name` | `string` | The file name to display in the compare UI for the temporarily uploaded file. |
| `language` | `string` | The language to use for localization of the compare UI. |
| `allow_download` | `bool` | True if the download options should be enabled in the compare UI, false otherwise. |
## Response: GetDocumentComparisonWithTempFileUrlResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `compare_url` | `string` | Receives the document comparison URL. |
---
# IRPCObjectOperations.GetExternalEditingDetails
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetExternalEditingDetails/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the information a client needs to open a file in an external editing system (SharePoint
Embedded).
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetExternalEditingDetails`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-editing-details`
- **Request:** [`GetExternalEditingDetailsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetExternalEditingDetails/index.md#request)
- **Response:** [`GetExternalEditingDetailsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetExternalEditingDetails/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients with SharePoint Embedded storage.
## Request: GetExternalEditingDetailsRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object whose file's authoring details you want. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version whose authoring details you want. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
## Response: GetExternalEditingDetailsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `external_type` | `string` | Specifies the system used to edit the file. Opaque to the server, tells the client how the data can be used. eg. "SharePointEmbedded" |
| `external_data` | `string` | Data the client can use to open the document. Interpretation depends on externalType. eg. in SharePointEmbedded this is the url of the document. |
| `external_preview_data` | `string` | Data the client can use to preview the document. Interpretation depends on externalType. eg. in SharePointEmbedded this is the preview url of the document. |
| `has_unversioned_changes` | `bool` | Indicates if the external file has changes which are not versioned in M-Files. |
| `last_modified_of_latest_change` | `string` | The last modified timestamp of the latest external version. |
---
# IRPCObjectOperations.GetFileDownloadUrl
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl/
Badges: `Vault API / core` `write` `session or assertion`
Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP
gateway.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetFileDownloadUrl`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-file-download-url`
- **Request:** [`GetFileDownloadUrlRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl/index.md#request)
- **Response:** [`GetFileDownloadUrlResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetFileDownloadUrlRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID. |
| `file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_id.internal_id` | `int32` | The file ID. |
| `file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `additional_data[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | An optional key-value pairs for additional data from the caller. Can be empty. |
| `additional_data[].key` | `string` | The name of the value. |
| `additional_data[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `additional_data[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `additional_data[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `additional_data[].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. |
## Response: GetFileDownloadUrlResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `url` | `string` | URL that can be used to download the file. |
## Related methods
- [GetFileDownloadUrl2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl2/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.GetFileDownloadUrl2
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl2/
Badges: `Vault API / core` `write` `session or assertion`
Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP
gateway.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetFileDownloadUrl2`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-file-download-url2`
- **Request:** [`GetFileDownloadUrlRequest2`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl2/index.md#request)
- **Response:** [`GetFileDownloadUrlResponse2`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl2/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetFileDownloadUrlRequest2
Request details for generating a download key for downloading multiple files.
> Nested 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_requests[]` | repeated [`FileDownloadUrlRequestData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileDownloadUrlRequestData/index.md) | Download requests. |
| `download_requests[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to download files from with the key. Not used if uploadID is not zero or fileRef is not empty. |
| `download_requests[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `download_requests[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `download_requests[].file_ids[]` | repeated [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File IDs in the object version to download with the key. Not used if uploadID is not zero or fileRef is not empty. |
| `download_requests[].file_ids[].type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `download_requests[].file_ids[].internal_id` | `int32` | The file ID. |
| `download_requests[].file_ids[].external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `download_requests[].upload_id` | `int32` | The identifier of the upload operation (from UploadTempFile or UploadTempFileCommit). If this is not zero, objVer and fileIds are ignored, and the download key is generated for downloading the file uploaded in the upload operation identified by this parameter. |
| `download_requests[].file_ref` | `string` | If not empty, the file_ref of a stateless upload ended with FileUploadEnd, and the download key is generated for downloading it; objVer and fileIds are ignored. At most one of uploadID and fileRef may be set. |
| `download_requests[].extension` | `string` | The extension of the file, not including the dot (e.g. "doc"). Used with fileRef only, as a file_ref has no file name. |
## Response: GetFileDownloadUrlResponse2
Response details for generating a download key for downloading multiple files.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `url` | `string` | The download URL. |
## Related methods
- [GetFileDownloadUrl](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileDownloadUrl/index.md): Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.
---
# IRPCObjectOperations.GetFileMalwareInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileMalwareInfo/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the malware scanning verdict of a file, as an advisory hint for a user interface.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetFileMalwareInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-file-malware-info`
- **Request:** [`GetFileMalwareInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileMalwareInfo/index.md#request)
- **Response:** [`GetFileMalwareInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileMalwareInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Used by the M-Files clients to warn before a download. An empty `malware_info.description` means
the file is clean or no verdict is available, for example when the vault does not scan files.
## Request: GetFileMalwareInfoRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The file to check,. Only pwszMasterStorageFileRef is read. |
| `file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `file.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file.file_ver.internal_version` | `int32` | The file version number. |
| `file.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file.title` | `string` | The file name without the extension. |
| `file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file.guid` | `string` | GUID of the file. |
| `file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `file.is_missing` | `bool` | True, if the file is missing. |
| `file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `file.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `file.flags.can_be_edited_externally` | `bool` | Next available value. |
| `file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
## Response: GetFileMalwareInfoResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `malware_info` | [`FileMalwareInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileMalwareInfo/index.md) | Malware verdict. Empty description = clean / no info available. |
| `malware_info.description` | `string` | Malware description from Master Storage when the file is flagged. Empty / null means "no warning". |
---
# IRPCObjectOperations.GetFileSize
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileSize/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the size of a specific file version in bytes.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetFileSize`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-file-size`
- **Request:** [`GetFileSizeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileSize/index.md#request)
- **Response:** [`GetFileSizeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetFileSize/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The same value as `File.size` in the version information. `obj_file_ver.file_ver` must name a
specific file version; `FILE_VER_TYPE_LATEST` fails with "Not found. (File -0 not found.)".
## Request: GetFileSizeRequest
> Nested 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_file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The file version. |
| `obj_file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver.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_file_ver.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_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
## Response: GetFileSizeResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_size` | `int64` | The size of the file. |
---
# IRPCObjectOperations.GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the identities and view IDs of unmanaged items of an external repository. Used by M-Files
clients; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-identities-and-views-of-multiple-unmanaged-reduced-items`
- **Request:** [`GetIdentitiesAndViewsOfMultipleUnmanagedReducedItemsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems/index.md#request)
- **Response:** [`GetIdentitiesAndViewsOfMultipleUnmanagedReducedItemsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetIdentitiesAndViewsOfMultipleUnmanagedReducedItems/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetIdentitiesAndViewsOfMultipleUnmanagedReducedItemsRequest
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Object IDs (managed or unmanaged) (represented by ObjIDArray struct.) |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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_missing_object_versions` | `bool` | True if the method is allowed to return less results than requested. This can happen if the user does not have access to all of the objects. |
## Response: GetIdentitiesAndViewsOfMultipleUnmanagedReducedItemsResponse
> Nested 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 [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Receives the managed object IDs of the requested objects with read access (represented by ObjID struct.) |
| `objects[].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). |
| `objects[].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`. |
| `objects[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `objects[].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. |
| `obj_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Receives the unmanaged object versions for requested objects with read access (represented by ObjVer struct.) |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `view_ids[]` | repeated [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Receives the primary view IDs for the requested objects with read access (represented by ItemID struct.) |
| `view_ids[].internal_id` | `int32` | The ID of the object or value list item. |
| `view_ids[].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. |
| `view_ids[].external_repository_id.connection` | `string` | The external repository connection identifier. |
| `view_ids[].external_repository_id.item` | `string` | External ID within the scope of the connection to external system. |
---
# IRPCObjectOperations.GetLatestFileVersion
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestFileVersion/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the latest version of a file and the object version it belongs to.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetLatestFileVersion`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-latest-file-version`
- **Request:** [`GetLatestFileVersionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestFileVersion/index.md#request)
- **Response:** [`GetLatestFileVersionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestFileVersion/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Use the returned `pobjver` and `file_version` to build an [ObjFileVer](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) for downloading.
## Request: GetLatestFileVersionRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file, as `File.file_ver.file_id`. |
| `file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_id.internal_id` | `int32` | The file ID. |
| `file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `allow_checked_out` | `bool` | True to get the file version of the checked-out version when the object is checked out to the caller. |
## Response: GetLatestFileVersionResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_version` | `int32` | The latest file version number. |
| `pobjver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The specific object version that contains that file version. |
| `pobjver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `pobjver.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). |
| `pobjver.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`. |
| `pobjver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `pobjver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `pobjver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `pobjver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `pobjver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
---
# IRPCObjectOperations.GetLatestObjectVersion
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the number and GUID of the latest version of an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetLatestObjectVersion`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-latest-object-version`
- **Request:** [`GetLatestObjectVersionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md#request)
- **Response:** [`GetLatestObjectVersionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestObjectVersion/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The cheapest way to turn an object ID into a specific version for the methods that do not accept
the latest-version marker. The returned version is `OBJ_VER_VERSION_TYPE_SPECIFIC`. A caller who
cannot read the object gets "Access denied." (0x800407E4).
## Request: GetLatestObjectVersionRequest
> Nested 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 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. |
| `allow_checked_out` | `bool` | True to get the checked-out version when the object is checked out to the caller. Otherwise, and for objects checked out to another user, the latest checked-in version. |
## Response: GetLatestObjectVersionResponse
> Nested 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_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest version, as a specific version. |
| `object_version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `object_version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `object_version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `object_version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `version_guid` | `string` | The GUID of that version. |
---
# IRPCObjectOperations.GetLatestVersionCommentOfMultipleObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestVersionCommentOfMultipleObjects/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the latest version comment of several objects.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetLatestVersionCommentOfMultipleObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-latest-version-comment-of-multiple-objects`
- **Request:** [`GetLatestVersionCommentOfMultipleObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestVersionCommentOfMultipleObjects/index.md#request)
- **Response:** [`GetLatestVersionCommentOfMultipleObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetLatestVersionCommentOfMultipleObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Each item of `obj_vers` must name a specific version; the `OBJ_VER_VERSION_TYPE_LATEST` marker and
version -1 fail with "Not found.".
## Request: GetLatestVersionCommentOfMultipleObjectsRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Objects. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetLatestVersionCommentOfMultipleObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `comments[]` | repeated [`LatestVersionComment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LatestVersionComment/index.md) | Receives the latest comments of the objects. |
| `comments[].comment` | [`VersionComment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VersionComment/index.md) | Latest comment. The typed value is unset if no latest comment is available. |
| `comments[].comment.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object version. |
| `comments[].comment.property_values[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties. |
| `comments[].more_comments_available` | `bool` | True if there are multiple comments available for the object. |
---
# IRPCObjectOperations.GetMultipleWorkflowStatesAndTransitions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the states and transitions of several workflows in one call, in a compressed binary form.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-multiple-workflow-states-and-transitions`
- **Request:** [`GetMultipleWorkflowStatesAndTransitionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions/index.md#request)
- **Response:** [`GetMultipleWorkflowStatesAndTransitionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients to fill their caches. The results are serialized and possibly compressed
byte arrays, not protobuf messages; use
[GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md)
instead.
## Request: GetMultipleWorkflowStatesAndTransitionsRequest
> Nested 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 the workflows. |
| `current_state` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | If the pointer is not unset, it points to a struct that specifies the current state of the object(s). If the pointer is unset, the bSelectable flags of all returned states will be true because transition rights cannot be checked in that case. |
| `current_state.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `current_state.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `current_state.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. |
| `current_state.data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `current_state.data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `current_state.data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `current_state.data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `current_state.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. |
| `current_state.data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `current_state.data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `current_state.data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `current_state.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. |
| `current_state.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. |
| `current_state.data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `current_state.data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `current_state.data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `current_state.data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
## Response: GetMultipleWorkflowStatesAndTransitionsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `states` | `bytes` | States. Compressed, unless pulUncompressedStatesLength is -1. |
| `uncompressed_states_length` | `uint32` | Receives the length of the uncompressed data. Set to -1 if pbytesData is not compressed. |
| `transitions` | `bytes` | Transitions. Compressed, unless pulUncompressedTransitionsLength is -1. |
| `uncompressed_transitions_length` | `uint32` | Receives the length of the uncompressed data. Set to -1 if pbytesData is not compressed. |
## Related methods
- [GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md): Gets the states and transitions of the given workflow.
- [GetMultipleWorkflowStatesAndTransitionsWithRightsCheck](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitionsWithRightsCheck/index.md): Gets the states and transitions of several workflows in one call, in a compressed binary form, with the user's rights checked.
---
# IRPCObjectOperations.GetMultipleWorkflowStatesAndTransitionsWithRightsCheck
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitionsWithRightsCheck/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the states and transitions of several workflows in one call, in a compressed binary form,
with the user's rights checked.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitionsWithRightsCheck`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-multiple-workflow-states-and-transitions-with-rights-check`
- **Request:** [`GetMultipleWorkflowStatesAndTransitionsWithRightsCheckRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitionsWithRightsCheck/index.md#request)
- **Response:** [`GetMultipleWorkflowStatesAndTransitionsWithRightsCheckResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitionsWithRightsCheck/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files clients; see
[GetMultipleWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions/index.md).
## Request: GetMultipleWorkflowStatesAndTransitionsWithRightsCheckRequest
> Nested 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 the workflows. |
## Response: GetMultipleWorkflowStatesAndTransitionsWithRightsCheckResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `states` | `bytes` | States. Compressed, unless pulUncompressedStatesLength is -1. |
| `uncompressed_states_length` | `uint32` | Receives the length of the uncompressed data. Set to -1 if pbytesData is not compressed. |
| `transitions` | `bytes` | Transitions. Compressed, unless pulUncompressedTransitionsLength is -1. |
| `uncompressed_transitions_length` | `uint32` | Receives the length of the uncompressed data. Set to -1 if pbytesData is not compressed. |
## Related methods
- [GetMultipleWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetMultipleWorkflowStatesAndTransitions/index.md): Gets the states and transitions of several workflows in one call, in a compressed binary form.
---
# IRPCObjectOperations.GetObjectFilesForModificationInEventHandler
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFilesForModificationInEventHandler/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the files of a checked-out object version for modification by an event handler. Used by
server-side vault applications; requires the vault-level right to edit and delete all objects.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectFilesForModificationInEventHandler`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-files-for-modification-in-event-handler`
- **Request:** [`GetObjectFilesForModificationInEventHandlerRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFilesForModificationInEventHandler/index.md#request)
- **Response:** [`GetObjectFilesForModificationInEventHandlerResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFilesForModificationInEventHandler/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetObjectFilesForModificationInEventHandlerRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetObjectFilesForModificationInEventHandlerResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | Results. |
| `files[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `files[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `files[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `files[].file_ver.internal_version` | `int32` | The file version number. |
| `files[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `files[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `files[].title` | `string` | The file name without the extension. |
| `files[].extension` | `string` | The file name extension without the dot, for example "pdf". |
| `files[].size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `files[].size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `files[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `files[].accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `files[].written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `files[].changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `files[].guid` | `string` | GUID of the file. |
| `files[].md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `files[].is_missing` | `bool` | True, if the file is missing. |
| `files[].is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `files[].flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `files[].flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `files[].flags.can_be_edited_externally` | `bool` | Next available value. |
| `files[].master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
## Related methods
- [GetObjectFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFiles/index.md): Gets the files of a specific object version.
---
# IRPCObjectOperations.GetObjectGUID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectGUID/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the GUID of an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectGUID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-guid`
- **Request:** [`GetObjectGUIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectGUID/index.md#request)
- **Response:** [`GetObjectGUIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectGUID/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The GUID is returned in braces and upper case, for example
`{ABE2580B-3D96-45D0-8A8A-38BFFC6E43E5}`, the same value as `ObjectLevelInfo.guid` in the version
information. The reverse lookup is
[GetObjIDByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjIDByGUID/index.md).
## Request: GetObjectGUIDRequest
> Nested 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 object. |
| `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. |
## Response: GetObjectGUIDResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pguid` | `string` | The object GUID, in braces. |
## Related methods
- [GetObjIDByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjIDByGUID/index.md): Gets the object ID of the object that has the given object GUID.
---
# IRPCObjectOperations.GetObjectHistory2
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory2/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Lists the existing versions of an object with their version information, oldest first.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectHistory2`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-history2`
- **Request:** [`GetObjectHistory2Request`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory2/index.md#request)
- **Response:** [`GetObjectHistory2Response`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory2/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Like [GetObjectHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/index.md), but each item is the
full version information, including the files of the version. The `base_properties` of the
versions are not filled; read properties with
[GetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md).
## Request: GetObjectHistory2Request
> Nested 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 object. |
| `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. |
## Response: GetObjectHistory2Response
> Nested 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 [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of each version, oldest first. |
| `results[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `results[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `results[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `results[].version_info.title` | `string` | The title (name) of the object in this version. |
| `results[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `results[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `results[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `results[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `results[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `results[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `results[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `results[].version_info.class_id` | `int32` | The class ID of the version. |
| `results[].version_info.version_guid` | `string` | The GUID of this version. |
| `results[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `results[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `results[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `results[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `results[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `results[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `results[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `results[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `results[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `results[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `results[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `results[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `results[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `results[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `results[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `results[].object_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 object (e.g. is the object deleted or a stub). |
| `results[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `results[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `results[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `results[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [GetObjectHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectHistory/index.md): Lists the existing versions of an object, oldest first.
- [GetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md): Gets the property values of one specific object version.
---
# IRPCObjectOperations.GetObjectInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfo/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the version information of one object without its property values.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-info`
- **Request:** [`GetObjectInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfo/index.md#request)
- **Response:** [`GetObjectInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
With `latest_version` true, the caller gets the latest checked-in version, or the checked-out
version if the object is checked out to the caller. With `latest_version` false, `version` must be
a specific version. A caller who cannot read the object gets "Access denied." (0x800407E4).
## Request: GetObjectInfoRequest
> Nested 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 object. |
| `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. |
| `latest_version` | `bool` | True to read the latest version, false to read `version`. |
| `version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The specific version to read when `latest_version` is false. |
| `version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetObjectInfoResponse
> Nested 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_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information, including the files of the version. |
| `object_info.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_info.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_info.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_info.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_info.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_info.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_info.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_info.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_info.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_info.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_info.version_info.class_id` | `int32` | The class ID of the version. |
| `object_info.version_info.version_guid` | `string` | The GUID of this version. |
| `object_info.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_info.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md): Gets the version information and the property values of one object, either its latest version or a specific version.
- [GetObjectInfoAndPropertiesWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata/index.md): Like GetObjectInfoAndProperties, but each property value also carries its value metadata.
---
# IRPCObjectOperations.GetObjectInfoAndPropertiesWithMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Like GetObjectInfoAndProperties, but each property value also carries its value metadata.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-info-and-properties-with-metadata`
- **Request:** [`GetObjectInfoAndPropertiesWithMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata/index.md#request)
- **Response:** [`GetObjectInfoAndPropertiesWithMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndPropertiesWithMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Takes the same parameters as
[GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md)
and behaves the same way. Each returned value also has `value_metadata`; for values without such
metadata the server returns `confidence` "-1".
## Request: GetObjectInfoAndPropertiesWithMetadataRequest
> Nested 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 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. |
| `latest_version` | `bool` | True to get the latest version. False to get the version specified by lDocVersion. |
| `allow_checked_out` | `bool` | True if a checked-out document version can be returned if the document is currently checked out to this user. Ignored if bLatestVersion is false. Note that even if this parameter is true, the method never returns a version that is checked out to some other user. |
| `doc_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The ID of the DocumentVersion. Ignored if bLatestVersion is true. |
| `doc_version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `doc_version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `doc_version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `doc_version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetObjectInfoAndPropertiesWithMetadataResponse
> Nested 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_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Receives the object version data (when found and visible). Note that when requesting the latest version, its ID parts (document ID and version ID) are always returned whenever the latest version exists although it's not visible to the user. |
| `object_info.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_info.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_info.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_info.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_info.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_info.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_info.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_info.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_info.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_info.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_info.version_info.class_id` | `int32` | The class ID of the version. |
| `object_info.version_info.version_guid` | `string` | The GUID of this version. |
| `object_info.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_info.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `property_array[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Receives the object version properties (when found and visible). |
| `property_array[].property_def` | `int32` | Property definition ID. |
| `property_array[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `property_array[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `property_array[].value.is_null_value` | `bool` | Is the value unset. |
| `property_array[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `property_array[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
## Related methods
- [GetObjectInfoAndProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfoAndProperties/index.md): Gets the version information and the property values of one object, either its latest version or a specific version.
- [GetObjectInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectInfo/index.md): Gets the version information of one object without its property values.
---
# IRPCObjectOperations.GetObjectsByExternalIds
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectsByExternalIds/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Finds objects of one object type by their external IDs.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjectsByExternalIds`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-objects-by-external-ids`
- **Request:** [`GetObjectsByExternalIdsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectsByExternalIds/index.md#request)
- **Response:** [`GetObjectsByExternalIdsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectsByExternalIds/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Matches only objects that have an external ID of their own (for example one set with
`SetExternalObjectID`), not the display IDs that equal the internal ID. IDs that match nothing,
and objects the caller cannot read, are left out without
an error, so the response can be shorter than the request. Each match is returned as the latest
version of the object.
## Request: GetObjectsByExternalIdsRequest
A request structure for GetObjectsByExternalIds RPC call. It contains all request data.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `external_ids[]` | repeated `string` | The external IDs to look up. Duplicates are ignored. |
| `object_type_id` | `int32` | The object type of the objects. |
## Response: GetObjectsByExternalIdsResponse
A response structure for GetObjectsByExternalIds RPC call. It contains all response data.
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The matching objects the caller can read. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Related methods
- [SetExternalObjectID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetExternalObjectID/index.md): Sets the external ID of an object.
---
# IRPCObjectOperations.GetObjIDByGUID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjIDByGUID/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the object ID of the object that has the given object GUID.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetObjIDByGUID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-obj-idby-guid`
- **Request:** [`GetObjIDByGUIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjIDByGUID/index.md#request)
- **Response:** [`GetObjIDByGUIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjIDByGUID/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The GUID is accepted with or without braces and in any letter case. A string that is not a GUID
fails with "The parameter is incorrect."; an unknown GUID with "Not found.".
## Request: GetObjIDByGUIDRequest
> Nested 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 object GUID, as returned by `GetObjectGUID` or `ObjectLevelInfo.guid`. |
## Response: GetObjIDByGUIDResponse
> Nested 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 object type and ID of the object. |
| `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. |
---
# IRPCObjectOperations.GetPromotedObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPromotedObjects/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Lists promoted objects of an external repository. Requires full control of the vault; the maximum
result count must be 1 to 1000.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetPromotedObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-promoted-objects`
- **Request:** [`GetPromotedObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPromotedObjects/index.md#request)
- **Response:** [`GetPromotedObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPromotedObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetPromotedObjectsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `external_repository` | `string` | If not null or empty, the external repository name. |
| `obj_id_last_seen` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The last seen object ID. Returns only objects that are after this object when ordered by managed object ID (object type, ID). |
| `obj_id_last_seen.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_last_seen.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_last_seen.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_id_last_seen.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. |
| `max_result_count` | `uint32` | The maximum number of results to return. |
## Response: GetPromotedObjectsResponse
> Nested 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_pairs[]` | repeated [`ObjIDPair`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjIDPair/index.md) | Receives the managed and unmanaged object IDs of the promoted objects. Ordered by managed object ID (object type, ID). |
| `obj_id_pairs[].obj_id_managed` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The managed object ID. |
| `obj_id_pairs[].obj_id_managed.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_pairs[].obj_id_managed.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_pairs[].obj_id_unmanaged` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The unmanaged object ID. |
| `obj_id_pairs[].obj_id_unmanaged.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_pairs[].obj_id_unmanaged.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`. |
---
# IRPCObjectOperations.GetPropertiesOfMultipleObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertiesOfMultipleObjects/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the property values of several specific object versions.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetPropertiesOfMultipleObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-properties-of-multiple-objects`
- **Request:** [`GetPropertiesOfMultipleObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertiesOfMultipleObjects/index.md#request)
- **Response:** [`GetPropertiesOfMultipleObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertiesOfMultipleObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Like [GetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md) for many versions: each
item of `objvers` must name a specific version, and the whole call fails with "Not found." if any
of them is missing. `properties[i]` belongs to `objvers[i]`.
## Request: GetPropertiesOfMultipleObjectsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callimp` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `objvers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Specific object versions. The latest-version marker is not accepted. |
| `objvers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `objvers[].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). |
| `objvers[].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`. |
| `objvers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `objvers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `objvers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `objvers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `objvers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetPropertiesOfMultipleObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `properties[]` | repeated [`PropertyValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueArray/index.md) | The property values of each version, in the request order. |
| `properties[].value[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values. |
| `properties[].value[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
## Related methods
- [GetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetProperties/index.md): Gets the property values of one specific object version.
---
# IRPCObjectOperations.GetPropertyValueWithMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertyValueWithMetadata/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets a property value and its metadata.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetPropertyValueWithMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-property-value-with-metadata`
- **Request:** [`GetPropertyValueWithMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertyValueWithMetadata/index.md#request)
- **Response:** [`GetPropertyValueWithMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetPropertyValueWithMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetPropertyValueWithMetadataRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `property_def` | `int32` | The property to add metadata to. |
## Response: GetPropertyValueWithMetadataResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `prop_val_with_metadata` | [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Receives the property value with metadata. |
| `prop_val_with_metadata.property_def` | `int32` | Property definition ID. |
| `prop_val_with_metadata.value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `prop_val_with_metadata.value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `prop_val_with_metadata.value.is_null_value` | `bool` | Is the value unset. |
| `prop_val_with_metadata.value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `prop_val_with_metadata.value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
---
# IRPCObjectOperations.GetRelationshipsForObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRelationshipsForObject/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the objects that a specific object version refers to, or that refer to it.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetRelationshipsForObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-relationships-for-object`
- **Request:** [`GetRelationshipsForObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRelationshipsForObject/index.md#request)
- **Response:** [`GetRelationshipsForObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRelationshipsForObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`obj_ver` must name a specific version; the `OBJ_VER_VERSION_TYPE_LATEST` marker fails with "Not
found.". `mode` selects the direction: `RELATIONSHIPS_MODE_FROM` (objects this version refers to),
`RELATIONSHIPS_MODE_TO` (objects that refer to it) or `RELATIONSHIPS_MODE_ALL`.
## Request: GetRelationshipsForObjectRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | A specific object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `mode` | [`RelationshipsMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.RelationshipsMode/index.md) | The desired relationships. Values: `RELATIONSHIPS_MODE_NONE` (0), `RELATIONSHIPS_MODE_FROM` (1), `RELATIONSHIPS_MODE_TO` (2), `RELATIONSHIPS_MODE_ALL` (3). |
## Response: GetRelationshipsForObjectResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `relationships_from[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The objects this version refers to. |
| `relationships_from[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `relationships_from[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `relationships_from[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `relationships_from[].version_info.title` | `string` | The title (name) of the object in this version. |
| `relationships_from[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `relationships_from[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `relationships_from[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `relationships_from[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `relationships_from[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `relationships_from[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `relationships_from[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `relationships_from[].version_info.class_id` | `int32` | The class ID of the version. |
| `relationships_from[].version_info.version_guid` | `string` | The GUID of this version. |
| `relationships_from[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `relationships_from[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `relationships_from[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `relationships_from[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `relationships_from[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `relationships_from[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `relationships_from[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `relationships_from[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `relationships_from[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `relationships_from[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `relationships_from[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `relationships_from[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `relationships_from[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `relationships_from[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `relationships_from[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `relationships_from[].object_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 object (e.g. is the object deleted or a stub). |
| `relationships_from[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `relationships_from[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `relationships_from[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `relationships_from[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `relationships_from[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `relationships_from[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `relationships_to[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The objects that refer to this version. |
| `relationships_to[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `relationships_to[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `relationships_to[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `relationships_to[].version_info.title` | `string` | The title (name) of the object in this version. |
| `relationships_to[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `relationships_to[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `relationships_to[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `relationships_to[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `relationships_to[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `relationships_to[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `relationships_to[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `relationships_to[].version_info.class_id` | `int32` | The class ID of the version. |
| `relationships_to[].version_info.version_guid` | `string` | The GUID of this version. |
| `relationships_to[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `relationships_to[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `relationships_to[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `relationships_to[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `relationships_to[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `relationships_to[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `relationships_to[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `relationships_to[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `relationships_to[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `relationships_to[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `relationships_to[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `relationships_to[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `relationships_to[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `relationships_to[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `relationships_to[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `relationships_to[].object_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 object (e.g. is the object deleted or a stub). |
| `relationships_to[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `relationships_to[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `relationships_to[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `relationships_to[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `relationships_to[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `relationships_to[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.GetRemoteRelationshipSourceInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipSourceInfo/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets what another vault needs to create a stub of this object, or to find a matching object.
Used by replication and cross-vault relationships; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetRemoteRelationshipSourceInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-remote-relationship-source-info`
- **Request:** [`GetRemoteRelationshipSourceInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipSourceInfo/index.md#request)
- **Response:** [`GetRemoteRelationshipSourceInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipSourceInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetRemoteRelationshipSourceInfoRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `partial_data` | [`RemoteRelationshipInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RemoteRelationshipInfo/index.md) | Partially filled information about the object. The JSON represents RemoteRelationshipInfo structure. |
| `partial_data.object_guid` | `string` | Object GUID. |
| `partial_data.vault_guid` | `string` | Object vault GUID. |
| `partial_data.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Obj ID. May identify the unmanaged object in the remote vault. |
| `partial_data.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). |
| `partial_data.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`. |
| `partial_data.object_type_name` | `string` | Object type name. |
| `partial_data.object_aliases` | `string` | Object type semantic aliases. |
| `partial_data.object_class_id` | `int32` | Class ID. |
| `partial_data.object_class_name` | `string` | Class name. |
| `partial_data.object_class_aliases` | `string` | Class semantic aliases. |
| `partial_data.object_external_id` | `string` | External ID of the object. |
| `partial_data.object_type_guid` | `string` | Object type GUID. |
| `partial_data.object_class_guid` | `string` | Class GUID. |
## Response: GetRemoteRelationshipSourceInfoResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `filled_data` | [`RemoteRelationshipInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RemoteRelationshipInfo/index.md) | Receives info about the object for creating relationship to another vault. The JSON represents RemoteRelationshipInfo structure. |
| `filled_data.object_guid` | `string` | Object GUID. |
| `filled_data.vault_guid` | `string` | Object vault GUID. |
| `filled_data.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Obj ID. May identify the unmanaged object in the remote vault. |
| `filled_data.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). |
| `filled_data.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`. |
| `filled_data.object_type_name` | `string` | Object type name. |
| `filled_data.object_aliases` | `string` | Object type semantic aliases. |
| `filled_data.object_class_id` | `int32` | Class ID. |
| `filled_data.object_class_name` | `string` | Class name. |
| `filled_data.object_class_aliases` | `string` | Class semantic aliases. |
| `filled_data.object_external_id` | `string` | External ID of the object. |
| `filled_data.object_type_guid` | `string` | Object type GUID. |
| `filled_data.object_class_guid` | `string` | Class GUID. |
---
# IRPCObjectOperations.GetRemoteRelationshipTargetInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipTargetInfo/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Finds the local object that matches an object of another vault, or the information for creating a
stub of it. Used by replication and cross-vault relationships; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetRemoteRelationshipTargetInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-remote-relationship-target-info`
- **Request:** [`GetRemoteRelationshipTargetInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipTargetInfo/index.md#request)
- **Response:** [`GetRemoteRelationshipTargetInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetRemoteRelationshipTargetInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetRemoteRelationshipTargetInfoRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `remote_` | [`RemoteRelationshipInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RemoteRelationshipInfo/index.md) | Info about the object in the remote vault. The JSON represents RemoteRelationshipInfo structure. |
| `remote_.object_guid` | `string` | Object GUID. |
| `remote_.vault_guid` | `string` | Object vault GUID. |
| `remote_.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Obj ID. May identify the unmanaged object in the remote vault. |
| `remote_.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). |
| `remote_.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`. |
| `remote_.object_type_name` | `string` | Object type name. |
| `remote_.object_aliases` | `string` | Object type semantic aliases. |
| `remote_.object_class_id` | `int32` | Class ID. |
| `remote_.object_class_name` | `string` | Class name. |
| `remote_.object_class_aliases` | `string` | Class semantic aliases. |
| `remote_.object_external_id` | `string` | External ID of the object. |
| `remote_.object_type_guid` | `string` | Object type GUID. |
| `remote_.object_class_guid` | `string` | Class GUID. |
## Response: GetRemoteRelationshipTargetInfoResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `found` | `bool` | True if the object exists already in the local vault, false if it needs to be created. |
| `local_` | [`RemoteRelationshipInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RemoteRelationshipInfo/index.md) | Receives info about the object in the local vault. The JSON represents RemoteRelationshipInfo structure. |
| `local_.object_guid` | `string` | Object GUID. |
| `local_.vault_guid` | `string` | Object vault GUID. |
| `local_.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Obj ID. May identify the unmanaged object in the remote vault. |
| `local_.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). |
| `local_.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`. |
| `local_.object_type_name` | `string` | Object type name. |
| `local_.object_aliases` | `string` | Object type semantic aliases. |
| `local_.object_class_id` | `int32` | Class ID. |
| `local_.object_class_name` | `string` | Class name. |
| `local_.object_class_aliases` | `string` | Class semantic aliases. |
| `local_.object_external_id` | `string` | External ID of the object. |
| `local_.object_type_guid` | `string` | Object type GUID. |
| `local_.object_class_guid` | `string` | Class GUID. |
---
# IRPCObjectOperations.GetSecurity
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurity/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the permissions (ACL) of an object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetSecurity`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-security`
- **Request:** [`GetSecurityRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurity/index.md#request)
- **Response:** [`GetSecurityResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurity/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The caller must be able to read the object version. The named ACL link is in
`acl.custom_component.named_acl_id`.
## Request: GetSecurityRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetSecurityResponse
> 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 |
|---|---|---|
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The ACL of the document version. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
## Related methods
- [GetSecurityOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurityOfMultipleObjects/index.md): Gets the permissions (ACL) of several object versions, in the order of `obj_vers`.
---
# IRPCObjectOperations.GetSecurityOfMultipleObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurityOfMultipleObjects/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the permissions (ACL) of several object versions, in the order of `obj_vers`.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetSecurityOfMultipleObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-security-of-multiple-objects`
- **Request:** [`GetSecurityOfMultipleObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurityOfMultipleObjects/index.md#request)
- **Response:** [`GetSecurityOfMultipleObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurityOfMultipleObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetSecurityOfMultipleObjectsRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object versions. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetSecurityOfMultipleObjectsResponse
> 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 |
|---|---|---|
| `acls[]` | repeated [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The ACLs of object versions. |
| `acls[].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. |
| `acls[].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. |
| `acls[].custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `acls[].custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acls[].custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acls[].custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acls[].custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acls[].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. |
| `acls[].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. |
| `acls[].custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `acls[].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. |
| `acls[].restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acls[].restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `acls[].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. |
| `acls[].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. |
| `acls[].additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acls[].additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
## Related methods
- [GetSecurity](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetSecurity/index.md): Gets the permissions (ACL) of an object version.
---
# IRPCObjectOperations.GetStateTransitionSignatureSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the signature settings for a state transition.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-state-transition-signature-settings`
- **Request:** [`GetStateTransitionSignatureSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings/index.md#request)
- **Response:** [`GetStateTransitionSignatureSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetStateTransitionSignatureSettings/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Tells whether a state transition requires an electronic signature and what the signature must
contain. Give `state_transition_id`, or -1 and the `from_state` and `to_state`. `found` is true if
the transition exists. Signing is done with the `signature` field of
[SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md).
## Request: GetStateTransitionSignatureSettingsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `state_transition_id` | `int32` | StateTransition ID. Ignored if -1. |
| `from_state` | `int32` | FromState ID. Ignored if lStateTransitionID is given. |
| `to_state` | `int32` | ToState ID. Ignored if lStateTransitionID is given. |
## Response: GetStateTransitionSignatureSettingsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `found` | `bool` | Receives true if the state transition was found. |
| `settings` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | Receives the signature settings. |
| `settings.is_required` | `bool` | True if this transition requires an electronic signature. |
| `settings.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). |
| `settings.fixed_prompt_details` | [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 2: Pre-defined reason |
| `settings.fixed_prompt_details.reason` | `string` | Reason text for the signature. This is typically a short description such as "Authorization for Use". |
| `settings.fixed_prompt_details.meaning` | `string` | Meaning text for the signature. This is typically a longer description such as "I have reviewed the document and authorize it for use". |
| `settings.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. |
| `settings.selectable_prompt_details[].reason` | `string` | Reason text for the signature. This is typically a short description such as "Authorization for Use". |
| `settings.selectable_prompt_details[].meaning` | `string` | Meaning text for the signature. This is typically a longer description such as "I have reviewed the document and authorize it for use". |
| `settings.user_selectable_reason_meaning_items_property_def` | `int32` | A property definition that represents items in value list. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `settings.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. |
| `settings.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. |
| `settings.add_metadata_reference_to_reason_meaning_item` | `bool` | Common prompt details. |
| `settings.prompt_free_form_text` | `bool` | True if a free-form text is prompted with the signature. |
| `settings.free_form_text_property_def` | `int32` | Signature details. boolean bFillReasonPropertyText; //!< Optional? boolean bFillMeaningPropertyText; //!< Optional? |
| `settings.manifestation_additional_info` | `string` | Additional information for the manifestation text for the signature. This is not shown to the user when signing. |
| `settings.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. |
| `settings.manifestation_property_def` | `int32` | Property definition to be used for storing the signature manifestation on the object. Ignored if bCreateSeparateSignatureObject is true. |
| `settings.signature_identifier` | `string` | Signature identifier. Required if bCreateSeparateSignatureObject is true. |
## Related methods
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
---
# IRPCObjectOperations.GetTemplateObjectsForObjectType
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplateObjectsForObjectType/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the template objects of an object type, with the Additional classes value of each.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetTemplateObjectsForObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-template-objects-for-object-type`
- **Request:** [`GetTemplateObjectsForObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplateObjectsForObjectType/index.md#request)
- **Response:** [`GetTemplateObjectsForObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplateObjectsForObjectType/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetTemplateObjectsForObjectTypeRequest
> Nested 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 get template objects of same type. |
## Response: GetTemplateObjectsForObjectTypeResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `template_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Resulting template objects objectversioninfo. |
| `template_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `template_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `template_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `template_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `template_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `template_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `template_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `template_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `template_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `template_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `template_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `template_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `template_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `template_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `template_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `template_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `template_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `template_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `template_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `template_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `template_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `template_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `template_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `template_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `template_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `template_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `template_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `template_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `template_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `template_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `template_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `template_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `template_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `template_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `template_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `addtional_classes_of_objects[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Resulting Addtional classes property value of each template objects. |
| `addtional_classes_of_objects[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `addtional_classes_of_objects[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `addtional_classes_of_objects[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `addtional_classes_of_objects[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `addtional_classes_of_objects[].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. |
---
# IRPCObjectOperations.GetTemplates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplates/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Gets the templates of an object type, optionally only those of one class or matching keywords.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetTemplates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-templates`
- **Request:** [`GetTemplatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplates/index.md#request)
- **Response:** [`GetTemplatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTemplates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: GetTemplatesRequest
A structure that specifies the request type for the GetTemplates 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 |
|---|---|---|
| `object_type_id` | `int32` | The object type of the templates. |
| `class_id` | optional `int32` | Optional class ID for fetching the templates of a specific class. |
| `search_keywords[]` | repeated `string` | The search keywords for the templates. |
## Response: GetTemplatesResponse
A structure that specifies the response type for the GetTemplates 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 |
|---|---|---|
| `templates[]` | repeated [`Template`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Template/index.md) | Templates. |
| `templates[].title` | `string` | The title of the template file. |
| `templates[].title_resource` | `string` | The resource key for the title of the template file. It will be available only for blank template file. |
| `templates[].file_template_id` | `string` | The file ID of the template file. It will be available only for blank templates. |
| `templates[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The template object ID. It will be available only for User defined templates. |
| `templates[].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). |
| `templates[].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`. |
| `templates[].class_id` | `int32` | The class of the object version. For blank templates it will be always 0, For user defined templates the class id of the object will be available. |
| `templates[].icon` | `bytes` | The icon for the template file. Currently it is not carrying any data. It will be implemented in future. |
| `templates[].restricted_to_classes[]` | repeated `uint32` | The array of restrict to class IDs. Currently it is not carrying any data. It will be implemented in future. |
---
# IRPCObjectOperations.GetTextContentForFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFile/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the plain text content of a file version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetTextContentForFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-text-content-for-file`
- **Request:** [`GetTextContentForFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFile/index.md#request)
- **Response:** [`GetTextContentForFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Prefer [GetTextContentForFileWithFormat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md),
which can also return Markdown. With `options.useplaintextcache` the server returns the text it
uses for full-text indexing, which can differ from a fresh extraction.
## Request: GetTextContentForFileRequest
> Nested 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_file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and the specific file version. |
| `obj_file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver.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_file_ver.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_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `options_obsolete` | `uint32` | Not used. Set `options` instead. |
| `options` | [`TEXTCONTENTEXTRACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TEXTCONTENTEXTRACTIONFLAGS/index.md) | Extraction flags. Leave unset for a fresh extraction. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.unpackcontainers` | `bool` | Unpack container files. |
| `options.useplaintextcache` | `bool` | Use plain text cache. This makes other options, such as UNPACKCONTAINERS and max. content size ineffective. The operation returns the text content in same way it is returned for e.g. search indexing. |
## Response: GetTextContentForFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `text_content` | `string` | Receives the plain text content of the file version. |
## Related methods
- [GetTextContentForFileWithFormat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md): Gets the text content of a file version as plain text or Markdown, and reports which format was produced.
---
# IRPCObjectOperations.GetTextContentForFileWithFormat
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the text content of a file version as plain text or Markdown, and reports which format was
produced.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-text-content-for-file-with-format`
- **Request:** [`GetTextContentForFileWithFormatRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md#request)
- **Response:** [`GetTextContentForFileWithFormatResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFileWithFormat/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Supported when the server's [ServerVaultCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md)
`get_text_content_with_format_supported` is true. Request `FILE_FORMAT_MARKDOWN` or
`FILE_FORMAT_PLAIN_TEXT`; any other format returns plain text. Always read `format_produced`: it
tells the format of `text_content`, which can be plain text even if Markdown was requested.
## Request: GetTextContentForFileWithFormatRequest
The request of GetTextContentForFileWithFormat: the file version and the requested text format.
> Nested 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_file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and the specific file version. |
| `obj_file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver.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_file_ver.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_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `option_flags` | [`TEXTCONTENTEXTRACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TEXTCONTENTEXTRACTIONFLAGS/index.md) | Extraction flags. Leave unset for a fresh extraction. |
| `option_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `option_flags.unpackcontainers` | `bool` | Unpack container files. |
| `option_flags.useplaintextcache` | `bool` | Use plain text cache. This makes other options, such as UNPACKCONTAINERS and max. content size ineffective. The operation returns the text content in same way it is returned for e.g. search indexing. |
| `requested_format` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | `FILE_FORMAT_MARKDOWN` or `FILE_FORMAT_PLAIN_TEXT`. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
## Response: GetTextContentForFileWithFormatResponse
The response of GetTextContentForFileWithFormat: the text and the format it was produced in.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `text_content` | `string` | The text, in the format given in `format_produced`. |
| `format_produced` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | The format of `text_content`. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
## Related methods
- [GetTextContentForFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForFile/index.md): Gets the plain text content of a file version.
---
# IRPCObjectOperations.GetTextContentForTemporaryFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile/
Badges: `Vault API / core` `write` `session or assertion`
Gets the plain text content of a file uploaded with UploadTempFile.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-text-content-for-temporary-file`
- **Request:** [`GetTextContentForTemporaryFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile/index.md#request)
- **Response:** [`GetTextContentForTemporaryFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetTextContentForTemporaryFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
The upload must be committed with
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) first, and it must
belong to the calling login session.
## Request: GetTextContentForTemporaryFileRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_session_id` | `int32` | The `upload_id` from `UploadTempFile`. |
## Response: GetTextContentForTemporaryFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `text_content` | `string` | Plaintext content. |
## Related methods
- [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.
---
# IRPCObjectOperations.GetVersionCommentHistory
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetVersionCommentHistory/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the version comments of an object up to a given version, oldest first.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetVersionCommentHistory`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-version-comment-history`
- **Request:** [`GetVersionCommentHistoryRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetVersionCommentHistory/index.md#request)
- **Response:** [`GetVersionCommentHistoryResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetVersionCommentHistory/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`obj_ver` must name a specific version, or have `internal_version` -1 for the whole history. The
`OBJ_VER_VERSION_TYPE_LATEST` marker fails with "The parameter is incorrect.".
## Request: GetVersionCommentHistoryRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version for which the version comment history is gathered. The version comment history includes this version and any older versions. If the version part is -1, the version comment history of the whole object is returned. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: GetVersionCommentHistoryResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `comments[]` | repeated [`VersionComment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VersionComment/index.md) | Results in ascending order. |
| `comments[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object version. |
| `comments[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `comments[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `comments[].property_values[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties. |
| `comments[].property_values[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `comments[].property_values[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
---
# IRPCObjectOperations.GetWorkflowsForClient
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/
Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets all the workflows in a format suitable for client.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetWorkflowsForClient`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-workflows-for-client`
- **Request:** [`GetWorkflowsForClientRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/index.md#request)
- **Response:** [`GetWorkflowsForClientResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Returns the workflows the user can see, each with its ID, name and `object_class_id`. In the Sample
Vault: workflow 106 "Reviewing drawings" with class 88.
## Request: GetWorkflowsForClientRequest
No fields.
## Response: GetWorkflowsForClientResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `workflows[]` | repeated [`Workflow`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Workflow/index.md) | Results Array. |
| `workflows[].id` | `int32` | Workflow ID. |
| `workflows[].name` | `string` | The name of the workflow. |
| `workflows[].object_class_id` | `int32` | The class this workflow can be used with. |
| `workflows[].description` | `string` | The user description of the workflow. |
| `workflows[].reserved1_obsolete` | `uint32` | Reserved, must be zero. |
| `workflows[].reserved2_obsolete` | `uint32` | Reserved, must be zero. |
---
# IRPCObjectOperations.GetWorkflowStateHistory
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStateHistory/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the workflow state history of an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/GetWorkflowStateHistory`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-workflow-state-history`
- **Request:** [`GetWorkflowStateHistoryRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStateHistory/index.md#request)
- **Response:** [`GetWorkflowStateHistoryResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStateHistory/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Returns the versions of the object in which the workflow state changed, oldest first, each with
its property values. `obj_ver` can be the LATEST marker. `max_history_states_to_return`
0 returns all; `more_history_states_available` tells whether the list was cut.
## Request: GetWorkflowStateHistoryRequest
Request for getting workflow state history of an object.
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `max_history_states_to_return` | `uint32` | The maximum number of states to return. Zero indicates no limit. |
## Response: GetWorkflowStateHistoryResponse
Response for getting workflow state history of an object.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `history_states[]` | repeated [`ObjVerWithProperties`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerWithProperties/index.md) | Object version and its property values. |
| `history_states[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object version. |
| `history_states[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `history_states[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `history_states[].property_values[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Properties. |
| `history_states[].property_values[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `history_states[].property_values[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `more_history_states_available` | `bool` | True if there are more history states available. |
---
# IRPCObjectOperations.HasFileDuplicates
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/HasFileDuplicates/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Tells whether a file with the given content (checksum) already exists in the vault.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/HasFileDuplicates`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/has-file-duplicates`
- **Request:** [`HasFileDuplicatesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/HasFileDuplicates/index.md#request)
- **Response:** [`HasFileDuplicatesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/HasFileDuplicates/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: HasFileDuplicatesRequest
> Nested 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_file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The obj file version. |
| `obj_file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_ver.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_file_ver.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_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
## Response: HasFileDuplicatesResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `has_duplicates` | `bool` | True, if the file version has duplicates. |
---
# IRPCObjectOperations.KeepUploadSessionAlive
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/KeepUploadSessionAlive/
Badges: `Vault API / core` `write` `session or assertion` `idempotent`
Keeps an upload from being removed for inactivity.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/KeepUploadSessionAlive`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/keep-upload-session-alive`
- **Request:** [`KeepUploadSessionAliveRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/KeepUploadSessionAlive/index.md#request)
- **Response:** [`KeepUploadSessionAliveResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/KeepUploadSessionAlive/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Supported when [ServerVaultCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md)
`keep_upload_session_alive_supported` is true; otherwise the call fails with "Not implemented.".
Call it at the interval given in `SessionData.keep_upload_session_alive_interval_in_seconds` of
the login response while you hold an upload that you have not used yet. A removed or consumed
upload gives "Not found. (The specified upload session does not exist.)".
## Request: KeepUploadSessionAliveRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The upload session ID to keep alive. |
## Response: KeepUploadSessionAliveResponse
No fields.
---
# IRPCObjectOperations.MigrateObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Migrates a promoted object. Requires full control of the vault; used by migration tools.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/MigrateObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/migrate-object`
- **Request:** [`MigrateObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObject/index.md#request)
- **Response:** [`MigrateObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: MigrateObjectRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `params` | [`MigrateObjectParams`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigrateObjectParams/index.md) | Parameters. |
| `params.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object to migrate. |
| `params.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). |
| `params.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`. |
| `params.set_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The properties to add/replace. |
| `params.set_properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `params.set_properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `params.source_object_policy` | [`MigrationSourceObjectPolicy`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MigrationSourceObjectPolicy/index.md) | Specifies what is done to the source object after the migration. Values: `MIGRATION_SOURCE_OBJECT_POLICY_UNSPECIFIED` (0), `MIGRATION_SOURCE_OBJECT_POLICY_KEEP` (1), `MIGRATION_SOURCE_OBJECT_POLICY_DELETE` (2), `MIGRATION_SOURCE_OBJECT_POLICY_DESTROY` (3). |
## Response: MigrateObjectResponse
> Nested 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_info` | [`MigratedObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigratedObjectInfo/index.md) | Results. |
| `object_info.object_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Extended object information. |
| `object_info.object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object_info.object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object_info.object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object_info.object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object_info.object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object_info.is_migration_source_object_policy_fulfilled` | `bool` | True if the source object policy has been fulfilled after the migration. |
| `object_info.error_code` | `int32` | Holds an error code if IsMigrationSourceObjectPolicyFulfilled = false. |
---
# IRPCObjectOperations.MigrateObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObjects/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Migrates and promotes objects. Requires full control of the vault; used by migration tools.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/MigrateObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/migrate-objects`
- **Request:** [`MigrateObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObjects/index.md#request)
- **Response:** [`MigrateObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/MigrateObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: MigrateObjectsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `params[]` | repeated [`MigrateObjectParams`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigrateObjectParams/index.md) | Parameters. |
| `params[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object to migrate. |
| `params[].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). |
| `params[].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`. |
| `params[].set_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The properties to add/replace. |
| `params[].set_properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `params[].set_properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `params[].source_object_policy` | [`MigrationSourceObjectPolicy`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MigrationSourceObjectPolicy/index.md) | Specifies what is done to the source object after the migration. Values: `MIGRATION_SOURCE_OBJECT_POLICY_UNSPECIFIED` (0), `MIGRATION_SOURCE_OBJECT_POLICY_KEEP` (1), `MIGRATION_SOURCE_OBJECT_POLICY_DELETE` (2), `MIGRATION_SOURCE_OBJECT_POLICY_DESTROY` (3). |
| `allow_missing_required_properties` | `bool` | If true, object can be set to have missing required parameters. |
## Response: MigrateObjectsResponse
> Nested 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_info[]` | repeated [`MigratedObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigratedObjectInfo/index.md) | Results. |
| `object_info[].object_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Extended object information. |
| `object_info[].object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `object_info[].object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `object_info[].object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `object_info[].object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `object_info[].object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `object_info[].is_migration_source_object_policy_fulfilled` | `bool` | True if the source object policy has been fulfilled after the migration. |
| `object_info[].error_code` | `int32` | Holds an error code if IsMigrationSourceObjectPolicyFulfilled = false. |
---
# IRPCObjectOperations.ModifyVersionTags
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ModifyVersionTags/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Replaces the version tags of an object version with the given set; an empty `tags` clears them.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/ModifyVersionTags`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-version-tags`
- **Request:** [`ModifyVersionTagsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ModifyVersionTags/index.md#request)
- **Response:** [`ModifyVersionTagsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ModifyVersionTags/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: ModifyVersionTagsRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `tags[]` | repeated `int32` | The new set of version tag IDs. Empty clears the tags of the version. |
## Response: ModifyVersionTagsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `modified_object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information of the modified document version after the operation. |
| `modified_object.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `modified_object.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `modified_object.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `modified_object.version_info.title` | `string` | The title (name) of the object in this version. |
| `modified_object.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `modified_object.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `modified_object.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `modified_object.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `modified_object.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `modified_object.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `modified_object.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `modified_object.version_info.class_id` | `int32` | The class ID of the version. |
| `modified_object.version_info.version_guid` | `string` | The GUID of this version. |
| `modified_object.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `modified_object.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `modified_object.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `modified_object.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `modified_object.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `modified_object.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `modified_object.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `modified_object.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `modified_object.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `modified_object.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `modified_object.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `modified_object.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `modified_object.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `modified_object.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `modified_object.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `modified_object.object_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 object (e.g. is the object deleted or a stub). |
| `modified_object.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `modified_object.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `modified_object.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `modified_object.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `modified_object.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `modified_object.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `modified_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Receives the property values of the modified document version after the operation. |
| `modified_properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `modified_properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `modified_properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `modified_properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `modified_properties[].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. |
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `latest_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The latest version of the object after the operation, if `is_latest_visible` is true. |
| `latest_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `latest_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `latest_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `latest_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `latest_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `latest_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `latest_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `latest_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `latest_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `latest_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `latest_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `latest_version.version_info.class_id` | `int32` | The class ID of the version. |
| `latest_version.version_info.version_guid` | `string` | The GUID of this version. |
| `latest_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `latest_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `latest_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `latest_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `latest_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `latest_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `latest_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `latest_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `latest_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `latest_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `latest_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `latest_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `latest_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `latest_version.object_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 object (e.g. is the object deleted or a stub). |
| `latest_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `latest_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `latest_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `latest_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.PrepareFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PrepareFile/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Prepares a PDF rendition of a file version and reports its size, extension and timestamp.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/PrepareFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/prepare-file`
- **Request:** [`PrepareFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PrepareFile/index.md#request)
- **Response:** [`PrepareFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PrepareFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Supports `FILE_FORMAT_PDF` and `FILE_FORMAT_DISPLAY_ONLY_PDF`; the text formats fail with "The
requested file format ... is not supported.". Calling it is optional:
[DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md) prepares the
rendition itself.
## Request: PrepareFileRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_ver` | [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The object and the specific file version. |
| `file_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `file_ver.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). |
| `file_ver.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`. |
| `file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `fileformat` | [`FileFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileFormat/index.md) | `FILE_FORMAT_PDF` or `FILE_FORMAT_DISPLAY_ONLY_PDF`. Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4). |
## Response: PrepareFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `available` | `bool` | True if the rendition is available. |
| `extension` | `string` | The extension of the rendition, for example "pdf". |
| `file_size` | `int64` | The size of the rendition in bytes. |
| `last_write_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The UTC timestamp of the prepared file. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [DownloadFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Begin/index.md): Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum.
---
# IRPCObjectOperations.PromoteUnmanagedObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PromoteUnmanagedObject/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Promotes objects of an external repository (unmanaged objects) to managed M-Files objects by giving
them metadata.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/PromoteUnmanagedObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/promote-unmanaged-object`
- **Request:** [`PromoteUnmanagedObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PromoteUnmanagedObject/index.md#request)
- **Response:** [`PromoteUnmanagedObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/PromoteUnmanagedObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: PromoteUnmanagedObjectRequest
> 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 |
|---|---|---|
| `properties[]` | repeated [`SetPropertiesParams`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetPropertiesParams/index.md) | Parameters (one set of parameters per object). |
| `properties[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The version to change, by number: the checked-out version if the caller has the object checked out, otherwise the latest checked-in version. The LATEST marker is not accepted. |
| `properties[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `properties[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `properties[].allow_modifying_checked_in_object` | `bool` | True to change a checked-in object: the server checks it out, applies the change and checks it in as one new version. |
| `properties[].fail_if_not_latest_checked_in_version` | `bool` | With `allow_modifying_checked_in_object`, true to fail if `obj_ver` is not the latest checked-in version. |
| `properties[].object_version_guid` | `string` | Optional `version_guid` of the version in `obj_ver`, checked together with `fail_if_not_latest_checked_in_version`. Leave empty normally. |
| `properties[].set_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values to add or replace. Other properties stay unchanged. |
| `properties[].set_properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].set_properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].is_full_set` | `bool` | True to treat `set_properties` as the full set and remove every other property the class does not list. `set_properties` must then include Class (100). Leave false. |
| `properties[].remove_properties[]` | repeated `int32` | Property definition IDs to remove. Properties listed by the class cannot be removed; set them empty instead. |
| `properties[].options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `properties[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `properties[].options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `properties[].options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `properties[].options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `properties[].options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `properties[].options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `properties[].options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `properties[].options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `properties[].acl_enforcing_mode` | [`ACLEnforcingMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ACLEnforcingMode/index.md) | Which ACL the server starts from when it updates the permissions; see SetProperties `acl_mode`. `ACLENFORCING_MODE_DISALLOW_CHANGES` is rejected. Values: `ACLENFORCING_MODE_USE_PREVIOUS` (0), `ACLENFORCING_MODE_USE_PROVIDED` (1), `ACLENFORCING_MODE_RESET_TO_DEFAULT` (2), `ACLENFORCING_MODE_DISALLOW_CHANGES` (3). |
| `properties[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions to use with `ACLENFORCING_MODE_USE_PROVIDED`. Unset otherwise. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `properties[].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. |
| `check_in` | `bool` | If true, the object is checked in immediately, otherwise the object is left to checked-out state. |
## Response: PromoteUnmanagedObjectResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `promoted_objects[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `promoted_objects[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `promoted_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `promoted_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `promoted_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `promoted_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `promoted_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `promoted_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `promoted_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `promoted_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `promoted_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `promoted_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `promoted_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `promoted_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `promoted_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `promoted_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `promoted_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `promoted_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `promoted_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `promoted_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `promoted_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `promoted_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `promoted_objects[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `promoted_objects[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `promoted_objects[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `promoted_objects[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `promoted_objects[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `promoted_objects[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `promoted_objects[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `promoted_objects[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `promoted_objects[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.RelayMasterStorageOperations
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RelayMasterStorageOperations/
Badges: `Vault API / core` `write` `session or assertion` `idempotent`
Relays file or object operations to Master Storage. Internal to M-Files; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RelayMasterStorageOperations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/relay-master-storage-operations`
- **Request:** [`RelayMasterStorageOperationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RelayMasterStorageOperations/index.md#request)
- **Response:** [`RelayMasterStorageOperationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RelayMasterStorageOperations/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: RelayMasterStorageOperationsRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object which is relayed to Master Storage. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version which is relayed to Master Storage. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `get_external_editing_details` | `bool` | If true, returns information required for starting a co-authoring session to the client. |
| `get_external_preview_details` | `bool` | If true, returns information required for previewing document having co-authoring capabilities to the client. |
| `get_external_version_data` | `bool` | If true, returns information like version id, last modified datetime and file size related to external version. |
| `get_labels` | `bool` | If true, returns labels (e.g. sensitivity / retention) attached to the file in Master Storage. |
## Response: RelayMasterStorageOperationsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `external_type` | `string` | Specifies the system used to edit the file. Opaque to the server, tells the client how the data can be used. eg. "SharePointEmbedded". Populated when request has getExternalEditingDetails or getExternalPreviewDetails flag set to true. |
| `external_data` | `string` | Data the client can use to open the document. Interpretation depends on externalType. eg. in SharePointEmbedded this is the url of the document. Populated when request has getExternalEditingDetails flag set to true. |
| `external_preview_data` | `string` | Data the client can use to preview the document. Interpretation depends on externalType. eg. in SharePointEmbedded this is the preview url of the document. Populated when request has getExternalPreviewDetails flag set to true. |
| `has_unversioned_changes` | `bool` | Indicates if the external file has changes which are not versioned in M-Files. Populated when request has getExternalVersionData set to true. |
| `last_modified_of_latest_change` | `string` | The last modified timestamp of the latest external version. Populated when request has getExternalVersionData set to true. |
| `labels` | `string` | Labels attached to the file in Master Storage. The server is opaque to the contents, but in practice the format is the SPE FileSensitivityLabelInfo shape -- the dedicated GetSensitivityLabels path parses the same payload into that struct, so callers should assume the SPE shape rather than genuine free-form. Populated when request has getLabels flag set to true. |
---
# IRPCObjectOperations.RemoveFromRecentlyAccessed
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveFromRecentlyAccessed/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Removes the specified objects from being shown in 'Recently Accessed by Me'.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RemoveFromRecentlyAccessed`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-from-recently-accessed`
- **Request:** [`RemoveFromRecentlyAccessedRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveFromRecentlyAccessed/index.md#request)
- **Response:** [`RemoveFromRecentlyAccessedResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveFromRecentlyAccessed/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
`object_count` must equal the number of `remove_objects`; otherwise the call fails with "The
parameter is incorrect. (ObjectCount does not match array size)". With `remove_all`,
the whole list is cleared.
## Request: RemoveFromRecentlyAccessedRequest
> Nested 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_count` | `int32` | The number of entries in `remove_objects`. Must match it. |
| `remove_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The objects to remove from the caller's Recently accessed list. |
| `remove_objects[].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). |
| `remove_objects[].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`. |
| `remove_objects[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `remove_objects[].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. |
| `remove_all` | `bool` | True to clear the whole list. |
## Response: RemoveFromRecentlyAccessedResponse
No fields.
---
# IRPCObjectOperations.RemoveObjectFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjectFile/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Removes a file from a document.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RemoveObjectFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-object-file`
- **Request:** [`RemoveObjectFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjectFile/index.md#request)
- **Response:** [`RemoveObjectFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjectFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The object must be checked out to the caller; `file_ver` is the file's version in the checked-out
version (check-out gives the files new file versions). The only file of a single-file document
cannot be removed: "The document is in single-file mode." Set Single file (22) to false first.
## Request: RemoveObjectFileRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
## Response: RemoveObjectFileResponse
> Nested 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_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The checked-out version after the operation. |
| `object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_version.version_info.class_id` | `int32` | The class ID of the version. |
| `object_version.version_info.version_guid` | `string` | The GUID of this version. |
| `object_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_version.object_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 object (e.g. is the object deleted or a stub). |
| `object_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [RemoveObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObject/index.md): Removes one object i.e. marks it deleted.
---
# IRPCObjectOperations.RemoveObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjects/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Marks several objects deleted in one transaction.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RemoveObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-objects`
- **Request:** [`RemoveObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjects/index.md#request)
- **Response:** [`RemoveObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
If any object fails (for example one that does not exist), none is deleted.
## Request: RemoveObjectsRequest
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Objects. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Response: RemoveObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `deleted_objects[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `deleted_objects[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `deleted_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `deleted_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `deleted_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `deleted_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `deleted_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `deleted_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `deleted_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `deleted_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `deleted_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `deleted_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `deleted_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `deleted_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `deleted_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `deleted_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `deleted_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `deleted_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `deleted_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `deleted_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `deleted_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `deleted_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `deleted_objects[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `deleted_objects[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `deleted_objects[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `deleted_objects[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `deleted_objects[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `deleted_objects[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `deleted_objects[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `deleted_objects[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `deleted_objects[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.RemoveProperty
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveProperty/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Removes one property value from an object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RemoveProperty`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-property`
- **Request:** [`RemovePropertyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveProperty/index.md#request)
- **Response:** [`RemovePropertyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveProperty/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The same rules as [UpdateProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateProperty/index.md) apply,
also to Comment (33). Properties the class requires cannot be removed.
## Request: RemovePropertyRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to remove the property of. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `property_id` | `int32` | The property to remove. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: RemovePropertyResponse
> 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 |
|---|---|---|
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties, and ACL of the modified version of the object after the operation. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `latest_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The latest version of the object after the operation, if `is_latest_visible` is true. |
| `latest_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `latest_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `latest_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `latest_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `latest_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `latest_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `latest_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `latest_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `latest_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `latest_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `latest_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `latest_version.version_info.class_id` | `int32` | The class ID of the version. |
| `latest_version.version_info.version_guid` | `string` | The GUID of this version. |
| `latest_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `latest_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `latest_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `latest_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `latest_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `latest_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `latest_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `latest_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `latest_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `latest_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `latest_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `latest_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `latest_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `latest_version.object_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 object (e.g. is the object deleted or a stub). |
| `latest_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `latest_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `latest_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `latest_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [UpdateProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateProperty/index.md): Sets one property value of an object version.
---
# IRPCObjectOperations.RemoveUploadSession
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/
Badges: `Vault API / core` `write` `session or assertion` `idempotent`
Removes an upload and its temporary file.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RemoveUploadSession`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-upload-session`
- **Request:** [`RemoveUploadSessionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md#request)
- **Response:** [`RemoveUploadSessionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Removing an upload that does not exist, for example one already consumed by
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md), succeeds.
## Request: RemoveUploadSessionRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The identifier of this upload operation. |
## Response: RemoveUploadSessionResponse
No fields.
## Related methods
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
---
# IRPCObjectOperations.RenameObjectFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RenameObjectFile/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Renames a document file.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/RenameObjectFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/rename-object-file`
- **Request:** [`RenameObjectFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RenameObjectFile/index.md#request)
- **Response:** [`RenameObjectFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RenameObjectFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The object must be checked out to the caller. Changes the file's title and extension, not its
content.
## Request: RenameObjectFileRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file to be renamed. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `title` | `string` | The new title of the file. |
| `extension` | `string` | The new extension of the file, not including the dot (e.g. "doc"). |
## Response: RenameObjectFileResponse
> Nested 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_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The checked-out version after the operation. |
| `object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_version.version_info.class_id` | `int32` | The class ID of the version. |
| `object_version.version_info.version_guid` | `string` | The GUID of this version. |
| `object_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_version.object_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 object (e.g. is the object deleted or a stub). |
| `object_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.ResolveConflict
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveConflict/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Resolves a replication conflict between an object and its conflict object. Used by replication
tools and M-Files clients; not for applications.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/ResolveConflict`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/resolve-conflict`
- **Request:** [`ResolveConflictRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveConflict/index.md#request)
- **Response:** [`ResolveConflictResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveConflict/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: ResolveConflictRequest
> Nested 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_idtarget` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The target object. |
| `obj_idtarget.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_idtarget.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_idtarget.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_idtarget.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. |
| `keep_this` | `bool` | True to resolve in favor of the target object, discard otherwise. |
| `preview` | `bool` | True to determine the affected objects without actual resolution. |
| `require_intended_objects` | `bool` | True to require intended objects for a non-preview invocation. |
| `ext_object_infos_intended[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | IDs of the objects intended to be affected (including the target). |
| `ext_object_infos_intended[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_infos_intended[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_infos_intended[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_infos_intended[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_infos_intended[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_infos_intended[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_infos_intended[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_infos_intended[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_infos_intended[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_infos_intended[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_infos_intended[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_infos_intended[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_infos_intended[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_infos_intended[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_infos_intended[].object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_infos_intended[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_infos_intended[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_infos_intended[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_infos_intended[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos_intended[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos_intended[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_infos_intended[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_infos_intended[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_infos_intended[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_infos_intended[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_infos_intended[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_infos_intended[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_infos_intended[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_infos_intended[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_infos_intended[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
## Response: ResolveConflictResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_object_infos[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Receives the info about the affected objects as JSOn array. |
| `ext_object_infos[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_infos[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_infos[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_infos[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_infos[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_infos[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_infos[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_infos[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_infos[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_infos[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_infos[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_infos[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_infos[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_infos[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_infos[].object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_infos[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_infos[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_infos[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_infos[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_infos[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_infos[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_infos[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_infos[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_infos[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_infos[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_infos[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_infos[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_infos[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `resolved` | `bool` | True if the indicated objects were really affected (as opposed to just returning the info). |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.ResolveManagedIDOfPromotedObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveManagedIDOfPromotedObject/
Badges: `Vault API / core` `read` `session or assertion` `idempotent`
Gets the managed object ID of an object that had the given unmanaged ID before it was promoted.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/ResolveManagedIDOfPromotedObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/resolve-managed-idof-promoted-object`
- **Request:** [`ResolveManagedIDOfPromotedObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveManagedIDOfPromotedObject/index.md#request)
- **Response:** [`ResolveManagedIDOfPromotedObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/ResolveManagedIDOfPromotedObject/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: ResolveManagedIDOfPromotedObjectRequest
> Nested 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) | Object ID of unmanaged object. (represented by ObjID struct.) |
| `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. |
## Response: ResolveManagedIDOfPromotedObjectResponse
> Nested 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_managed` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The ObjID of the managed object. |
| `id_managed.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). |
| `id_managed.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`. |
| `id_managed.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `id_managed.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. |
---
# IRPCObjectOperations.Rollback
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/Rollback/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Rolls back to an older version. Creates a new version that is a copy of the specified old version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/Rollback`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/rollback`
- **Request:** [`RollbackRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/Rollback/index.md#request)
- **Response:** [`RollbackResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/Rollback/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Creates a new version that is a copy of the given older version; the versions in between are kept.
## Request: RollbackRequest
> Nested 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 object. |
| `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. |
| `rollback_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version to copy, with `OBJ_VER_VERSION_TYPE_SPECIFIC` and its number. |
| `rollback_version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `rollback_version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `rollback_version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `rollback_version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: RollbackResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_object_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Information about the object after the operation. |
| `ext_object_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_info.object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.SetDocEventSubscriptions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetDocEventSubscriptions/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Replaces the caller's event subscriptions for an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetDocEventSubscriptions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-doc-event-subscriptions`
- **Request:** [`SetDocEventSubscriptionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetDocEventSubscriptions/index.md#request)
- **Response:** [`SetDocEventSubscriptionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetDocEventSubscriptions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: SetDocEventSubscriptionsRequest
> Nested 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 object ID. (represented by ObjID struct.) |
| `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. |
| `utf8szeventsubs[]` | repeated [`EventSubscription`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventSubscription/index.md) | Event subscriptions. |
| `utf8szeventsubs[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. [ switch_is( eventtype ) ] EventTypeSpecificDataUnion etsdu; //!< Additional event type -specific data as a union. |
## Response: SetDocEventSubscriptionsResponse
No fields.
---
# IRPCObjectOperations.SetExternalObjectID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetExternalObjectID/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Sets the external ID of an object.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetExternalObjectID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-external-object-id`
- **Request:** [`SetExternalObjectIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetExternalObjectID/index.md#request)
- **Response:** [`SetExternalObjectIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetExternalObjectID/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Requires the vault-level right to edit and delete all objects.
## Request: SetExternalObjectIDRequest
> Nested 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 object ID. (represented by ObjID struct.) |
| `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. |
| `ext_id` | `string` | The new external ID for the specified object. |
## Response: SetExternalObjectIDResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.SetFavoritesMultiple
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetFavoritesMultiple/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Adds and removes objects from the favorites collection of the user.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetFavoritesMultiple`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-favorites-multiple`
- **Request:** [`SetFavoritesMultipleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetFavoritesMultiple/index.md#request)
- **Response:** [`SetFavoritesMultipleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetFavoritesMultiple/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Changes the caller's Favorites.
## Request: SetFavoritesMultipleRequest
> Nested 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_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The objects that are added to the Favorites collection. |
| `add_objects[].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). |
| `add_objects[].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`. |
| `add_objects[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `add_objects[].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. |
| `remove_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The objects that are removed from the Favorites collection. |
| `remove_objects[].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). |
| `remove_objects[].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`. |
| `remove_objects[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `remove_objects[].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. |
| `remove_all` | `bool` | True if the specified set of favorite objects should replace the existing collection. In this case the removed objects are also included in the return values. |
## Response: SetFavoritesMultipleResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `affected_objects[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `affected_objects[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `affected_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `affected_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `affected_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `affected_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `affected_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `affected_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `affected_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `affected_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `affected_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `affected_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `affected_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `affected_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `affected_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `affected_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `affected_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `affected_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `affected_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `affected_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `affected_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `affected_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `affected_objects[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `affected_objects[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `affected_objects[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `affected_objects[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `affected_objects[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `affected_objects[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `affected_objects[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `affected_objects[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `affected_objects[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.SetObjectActive
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectActive/
Badges: `Vault API / core` `write` `session or assertion`
Clears the draft (pending-upload) flag on an object, leaving it checked out. Used when
the file upload has completed and the object should become a normal checked-out object without
being checked in. Never checks the object in; a safe no-op on a non-draft.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetObjectActive`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-object-active`
- **Request:** [`SetObjectActiveRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectActive/index.md#request)
- **Response:** [`SetObjectActiveResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectActive/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Completes the draft flow of
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) (`draft: true`): after
the file content has been uploaded, this clears the draft flag. The object stays checked out; check
it in with [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md).
## Request: SetObjectActiveRequest
A request structure for the SetObjectActive RPC call. It contains all request data.
Identifies the draft object whose draft (pending-upload) flag is cleared.
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The draft object version to make active. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
## Response: SetObjectActiveResponse
> 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 |
|---|---|---|
| `updated_object` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The object after clearing the draft flag (still checked out), with its properties and ACL. |
| `updated_object.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `updated_object.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_object.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_object.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `updated_object.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `updated_object.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `updated_object.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `updated_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. |
| `updated_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. |
| `updated_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. |
| `updated_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. |
| `updated_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. |
| `updated_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. |
| `updated_object.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `updated_object.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `updated_object.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `updated_object.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `updated_object.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
## Related methods
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [CheckIn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/CheckIn/index.md): Checks in one object.
---
# IRPCObjectOperations.SetObjectGUID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectGUID/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Sets the Object GUID of the specified object. NOTE: In general, the identity of an object should remain unchanged. Use this method in special circumstances only.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetObjectGUID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-object-guid`
- **Request:** [`SetObjectGUIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectGUID/index.md#request)
- **Response:** [`SetObjectGUIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectGUID/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Requires the vault-level right to edit and delete all objects.
## Request: SetObjectGUIDRequest
> Nested 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 object ID. (represented by ObjID struct.) |
| `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. |
| `guid` | `string` | The new Object GUID for the specified object. |
## Response: SetObjectGUIDResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.SetObjectLevelProperty
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectLevelProperty/
Badges: `Vault API / core` `write` `session or assertion` `idempotent` `returns metadata structure version`
Sets a property that belongs to the object as a whole rather than to one version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetObjectLevelProperty`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-object-level-property`
- **Request:** [`SetObjectLevelPropertyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectLevelProperty/index.md#request)
- **Response:** [`SetObjectLevelPropertyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetObjectLevelProperty/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: SetObjectLevelPropertyRequest
> Nested 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 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. |
| `property` | [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The new property. |
| `property.property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `property.value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `property.value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property.value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property.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. |
| `options` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `options.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `options.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `options.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `options.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `options.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `options.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: SetObjectLevelPropertyResponse
> Nested 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` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Information about the object after the operation. (represented by ExtObjectInfo struct.) |
| `result.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `result.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `result.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `result.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `result.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `result.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `result.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `result.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `result.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `result.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `result.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `result.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `result.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `result.object_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 object (e.g. is the object deleted or a stub). |
| `result.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `result.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `result.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `result.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `result.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `result.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `result.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `result.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `result.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `result.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `result.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `result.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `result.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `result.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `result.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.SetPropertiesWithMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Adds, replaces or removes property values of an object, also storing metadata about each value.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-properties-with-metadata`
- **Request:** [`SetPropertiesWithMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata/index.md#request)
- **Response:** [`SetPropertiesWithMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Same request fields and rules as
[SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md); each value also carries
`value_metadata` (see [TypedValueMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md)).
## Request: SetPropertiesWithMetadataRequest
> 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 |
|---|---|---|
| `signature` | [`SESSIONID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SESSIONID/index.md) | The electronic signature that might be required by a workflow state transition operation. |
| `signature.value` | `bytes` | 64-byte session ID in RPC interface. 48 bytes in gRPC interface. |
| `obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to set the properties of. (represented by ObjVer struct.) |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `allow_modifying_checked_in_object` | `bool` | If true, modifying a checked-in document is possible. The server automatically checks out, modifies and checks in the document. |
| `allow_missing_required_properties` | `bool` | If true, object can be set to have missing required parameters. |
| `fail_if_newer_version_exists` | `bool` | If bAllowModifyingCheckedInDoc is true, this parameter defines if the method should fail if there already is a checked-in version that is newer than lDocVersion. |
| `version_guid` | `string` | If not GUID_NULL, specifies the ObjVersionGUID of the version to set the properties of. The server will use this GUID for additional checks if bFailIfNotLatestCheckedInVersion is true. |
| `properties[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | The properties to add/replace. |
| `properties[].property_def` | `int32` | Property definition ID. |
| `properties[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `properties[].value.is_null_value` | `bool` | Is the value unset. |
| `properties[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `properties[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
| `remove_unspecified_properties` | `bool` | True if ppropvalSet contains the full set of properties. Other existing properties will be removed. |
| `remove[]` | repeated `int32` | The properties to remove (property definition IDs). |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
| `acl_mode` | [`ACLEnforcingMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ACLEnforcingMode/index.md) | ACL enforcing mode. Values: `ACLENFORCING_MODE_USE_PREVIOUS` (0), `ACLENFORCING_MODE_USE_PROVIDED` (1), `ACLENFORCING_MODE_RESET_TO_DEFAULT` (2), `ACLENFORCING_MODE_DISALLOW_CHANGES` (3). |
| `acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The provided ACL. Can be unset. |
| `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. |
| `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. |
| `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. |
| `acl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `acl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `acl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `acl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `acl.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. |
| `acl.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. |
| `acl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `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. |
| `acl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `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. |
| `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. |
| `acl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `acl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
## Response: SetPropertiesWithMetadataResponse
> Nested 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_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Receives the object version data (when found and visible). Note that when requesting the latest version, its ID parts (document ID and version ID) are always returned whenever the latest version exists although it's not visible to the user. |
| `object_info.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_info.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_info.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_info.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_info.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_info.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_info.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_info.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_info.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_info.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_info.version_info.class_id` | `int32` | The class ID of the version. |
| `object_info.version_info.version_guid` | `string` | The GUID of this version. |
| `object_info.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_info.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `property_array[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Receives the object version properties (when found and visible). |
| `property_array[].property_def` | `int32` | Property definition ID. |
| `property_array[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `property_array[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `property_array[].value.is_null_value` | `bool` | Is the value unset. |
| `property_array[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `property_array[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
## Related methods
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
- [SetPropertiesWithMetadataAttributedTo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/index.md): Sets property values with metadata and records the change as made by a built-in agent user.
---
# IRPCObjectOperations.SetPropertiesWithMetadataAttributedTo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Sets property values with metadata and records the change as made by a built-in agent user.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-properties-with-metadata-attributed-to`
- **Request:** [`SetPropertiesWithMetadataAttributedToRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/index.md#request)
- **Response:** [`SetPropertiesWithMetadataAttributedToResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadataAttributedTo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Used by M-Files automatic metadata features. `attributed_to_user_id` names the built-in agent user;
0 records no attribution.
## Request: SetPropertiesWithMetadataAttributedToRequest
> Nested 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_version` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version for which the properties belong to. |
| `object_version.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `object_version.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). |
| `object_version.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`. |
| `object_version.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `object_version.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `object_version.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `object_version.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `object_version.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `allow_modifying_checked_in_object` | `bool` | Whether to allow modifying a checked-in object (automatic checkout and checkin). |
| `allow_missing_required_properties` | `bool` | Whether to allow missing required properties on the set. |
| `property_values[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | The property values with metadata to set. |
| `property_values[].property_def` | `int32` | Property definition ID. |
| `property_values[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `property_values[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `property_values[].value.is_null_value` | `bool` | Is the value unset. |
| `property_values[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `property_values[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
| `attributed_to_user_id` | `int32` | Built-in agent user ID to attribute the change to, or 0 for no attribution. |
## Response: SetPropertiesWithMetadataAttributedToResponse
> 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 |
|---|---|---|
| `object_version` | [`ObjectVersionExWPWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWPWithMetadata/index.md) | The object version and properties (with metadata) after the operation. |
| `object_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_version.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_version.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_version.properties[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Property values, or an empty array. |
| `object_version.properties[].property_def` | `int32` | Property definition ID. |
| `object_version.properties[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `object_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_version.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. |
| `object_version.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. |
| `object_version.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. |
| `object_version.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. |
| `object_version.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. |
| `object_version.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. |
| `object_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_version.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_version.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_version.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_version.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
## Related methods
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
- [SetPropertiesWithMetadata](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertiesWithMetadata/index.md): Adds, replaces or removes property values of an object, also storing metadata about each value.
---
# IRPCObjectOperations.SetPropertyValueMetadata
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertyValueMetadata/
Badges: `Vault API / core` `write` `session or assertion`
Changes the metadata of property values without changing the values.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetPropertyValueMetadata`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-property-value-metadata`
- **Request:** [`SetPropertyValueMetadataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertyValueMetadata/index.md#request)
- **Response:** [`SetPropertyValueMetadataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetPropertyValueMetadata/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: SetPropertyValueMetadataRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to set the properties of. (represented by ObjVer struct.) |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `property[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | The properties to add/replace. |
| `property[].property_def` | `int32` | Property definition ID. |
| `property[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `property[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `property[].value.is_null_value` | `bool` | Is the value unset. |
| `property[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `property[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
## Response: SetPropertyValueMetadataResponse
> Nested 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_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Receives the object version data (when found and visible). Note that when requesting the latest version, its ID parts (document ID and version ID) are always returned whenever the latest version exists although it's not visible to the user. |
| `object_info.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_info.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_info.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_info.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_info.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_info.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_info.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_info.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_info.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_info.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_info.version_info.class_id` | `int32` | The class ID of the version. |
| `object_info.version_info.version_guid` | `string` | The GUID of this version. |
| `object_info.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_info.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `property_array[]` | repeated [`PropertyValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueWithMetadata/index.md) | Receives the object version properties (when found and visible). |
| `property_array[].property_def` | `int32` | Property definition ID. |
| `property_array[].value` | [`TypedValueWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueWithMetadata/index.md) | The value of the property. |
| `property_array[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | Data type. Note. Name of the property can't be isNull because name collision with Objective-C reserved name. |
| `property_array[].value.is_null_value` | `bool` | Is the value unset. |
| `property_array[].value.data` | [`TypedValueUnionWithMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnionWithMetadata/index.md) | The value data as a union, if set. |
| `property_array[].value.value_metadata` | [`TypedValueMetadata`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueMetadata/index.md) | The metadata about the typed value. If the value is a Lookup or MSLookup, this data will be in that struct. |
---
# IRPCObjectOperations.SetTier
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetTier/
Badges: `Vault API / core` `write` `session or assertion`
Moves objects between storage tiers.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/SetTier`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-tier`
- **Request:** [`SetTierRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetTier/index.md#request)
- **Response:** [`SetTierResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetTier/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Requires full control of the vault. Objects that could not be moved are listed in `failed`.
## Request: SetTierRequest
A request structure for SetTier RPC call. It contains all request data.
> Nested 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 [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Objects to set the tier for. |
| `objects[].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). |
| `objects[].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`. |
| `objects[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `objects[].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. |
| `force_undo_checkout` | `bool` | True to force undo checkout for checked out objects. |
| `can_skip` | `bool` | True if objects can be skipped (e.g. when preconditions aren't met). |
| `storage_tier` | [`StorageTier`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.StorageTier/index.md) | The storage tier to set. Values: `STORAGE_TIER_UNDEFINED` (0), `STORAGE_TIER_CONTENT` (1), `STORAGE_TIER_RECORD` (2). |
| `output_result_data` | `bool` | True if the response should contain result data. |
## Response: SetTierResponse
A response structure for SetTier RPC call. It contains all response data.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `failed[]` | repeated [`ObjectOperationStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectOperationStatus/index.md) | Objects that failed (tier couldn't be set). |
| `failed[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `failed[].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). |
| `failed[].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`. |
| `failed[].message` | `string` | Status message. |
| `failed[].status` | `int32` | Status code, HRESULT. |
| `results[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Resulting object information if requested. |
| `results[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `results[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `results[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `results[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `results[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `results[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `results[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `results[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `results[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `results[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `results[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `results[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `results[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `results[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `results[].object_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 object (e.g. is the object deleted or a stub). |
| `results[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `results[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `results[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `results[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `results[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `results[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `results[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `results[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `results[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `results[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `results[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `results[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `results[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
---
# IRPCObjectOperations.UndeleteObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObjects/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Restores several deleted objects. Requires the vault-level right to undelete objects.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UndeleteObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/undelete-objects`
- **Request:** [`UndeleteObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObjects/index.md#request)
- **Response:** [`UndeleteObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndeleteObjects/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Request: UndeleteObjectsRequest
> Nested 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_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | Objects. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
## Response: UndeleteObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_object_infos[]` | repeated [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `ext_object_infos[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_object_infos[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_object_infos[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_object_infos[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_object_infos[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_object_infos[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_object_infos[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_object_infos[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_object_infos[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_object_infos[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_object_infos[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_object_infos[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_object_infos[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_object_infos[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_object_infos[].object_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 object (e.g. is the object deleted or a stub). |
| `ext_object_infos[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_object_infos[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_object_infos[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_object_infos[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_object_infos[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_object_infos[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_object_infos[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_object_infos[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_object_infos[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_object_infos[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_object_infos[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_object_infos[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_object_infos[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_object_infos[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.UndoCheckoutMultiple
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckoutMultiple/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Undoes the check-out of several objects in one call.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UndoCheckoutMultiple`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/undo-checkout-multiple`
- **Request:** [`UndoCheckoutMultipleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckoutMultiple/index.md#request)
- **Response:** [`UndoCheckoutMultipleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckoutMultiple/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Each object behaves as in [UndoCheckout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md).
## Request: UndoCheckoutMultipleRequest
> Nested 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_vers[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object versions. |
| `obj_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_vers[].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_vers[].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_vers[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_vers[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_vers[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_vers[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_vers[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `force` | `bool` | If true, undo checkout is performed even if the document was not checked out to the caller (if the caller has sufficient rights). |
## Response: UndoCheckoutMultipleResponse
> Nested 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 [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | Results. |
| `results[].is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `results[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `results[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `results[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `results[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `results[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `results[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `results[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `results[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `results[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `results[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `results[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `results[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `results[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `results[].object_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 object (e.g. is the object deleted or a stub). |
| `results[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `results[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `results[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `results[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `results[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `results[].is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `results[].latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `results[].latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `results[].latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `results[].latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `results[].latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `results[].original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `results[].original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `results[].original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [UndoCheckout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UndoCheckout/index.md): Undoes the checkout of one object.
---
# IRPCObjectOperations.UpdateMetadataInFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateMetadataInFile/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Writes the object's metadata into the properties embedded in its files (for formats that support
it).
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UpdateMetadataInFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-metadata-in-file`
- **Request:** [`UpdateMetadataInFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateMetadataInFile/index.md#request)
- **Response:** [`UpdateMetadataInFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateMetadataInFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
An unset `file_id` part updates all files. With `fail_on_unsupported_file`, a file format that
cannot carry embedded metadata fails the call.
## Request: UpdateMetadataInFileRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file which is updated. IF the file part of the ID is empty then all files are updated. |
| `file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_id.internal_id` | `int32` | The file ID. |
| `file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `fail_on_unsupported_file` | `bool` | If true, throw an exception if a file for which embedded metadata is not supported is encountered. |
## Response: UpdateMetadataInFileResponse
> Nested 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_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Receives information about the latest version of the document after the operation. |
| `object_info.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_info.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_info.version_info.title` | `string` | The title (name) of the object in this version. |
| `object_info.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_info.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_info.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_info.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_info.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_info.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_info.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_info.version_info.class_id` | `int32` | The class ID of the version. |
| `object_info.version_info.version_guid` | `string` | The GUID of this version. |
| `object_info.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_info.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_info.object_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 object (e.g. is the object deleted or a stub). |
| `object_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.UpdateObjectModificationInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateObjectModificationInfo/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Overwrites the creation and last modification information (who and when) of a checked-out object.
This is a specific method for updating the creation and last modification info of an object.
The operation requires full control of vault and the object must be checked out.
The creation related information can be updated only for the first version of the object before it is
checked in.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UpdateObjectModificationInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-object-modification-info`
- **Request:** [`UpdateObjectModificationInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateObjectModificationInfo/index.md#request)
- **Response:** [`UpdateObjectModificationInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateObjectModificationInfo/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Requires the vault-level right to change the full control role, normally held by vault
administrators. Used by migration and import tools.
## Request: UpdateObjectModificationInfoRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to set the values of. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The properties to add/replace arrau. |
| `properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `properties[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `properties[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `properties[].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. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: UpdateObjectModificationInfoResponse
> 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 |
|---|---|---|
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties, and ACL of the modified version of the object after the operation. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `latest_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The latest version of the object after the operation, if `is_latest_visible` is true. |
| `latest_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `latest_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `latest_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `latest_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `latest_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `latest_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `latest_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `latest_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `latest_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `latest_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `latest_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `latest_version.version_info.class_id` | `int32` | The class ID of the version. |
| `latest_version.version_info.version_guid` | `string` | The GUID of this version. |
| `latest_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `latest_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `latest_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `latest_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `latest_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `latest_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `latest_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `latest_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `latest_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `latest_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `latest_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `latest_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `latest_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `latest_version.object_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 object (e.g. is the object deleted or a stub). |
| `latest_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `latest_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `latest_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `latest_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCObjectOperations.UpdateProperty
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateProperty/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Sets one property value of an object version.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UpdateProperty`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-property`
- **Request:** [`UpdatePropertyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateProperty/index.md#request)
- **Response:** [`UpdatePropertyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UpdateProperty/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
For ordinary properties the object must be checked out to the caller; on a checked-in version the
call fails with "The object is not checked out." Properties that belong to a single
version, such as Comment (33), can also be set on a checked-in version, including an older one;
this needs more than edit access: a normal user got "You do not have sufficient access rights to
change the property "Comment" in checked-in versions." where a vault administrator succeeded, and no
new version was created. Use
[SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md) for ordinary changes.
## Request: UpdatePropertyRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to set the property of. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `property` | [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | The updated property. |
| `property.property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `property.value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `property.value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `property.value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `property.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. |
| `object_flags` | [`OBJECTOPFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTOPFLAGS/index.md) | Flags that control this operation. |
| `object_flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `object_flags.require_read_access_after_operation` | `bool` | Requires read access to the object after the object operation. If available, the operation fails if the user does not have read access to the object after the operation. |
| `object_flags.require_edit_access_after_operation` | `bool` | Requires edit access to the object after the object operation. If available, the operation fails if the user does not have edit access to the object after the operation. |
| `object_flags.disallow_name_change` | `bool` | If specified, the operation will fail if it causes a change in the object version's name. |
| `object_flags.require_change_permissions_access_after_operation` | `bool` | Requires security change access to the object after the object operation. If available, the operation fails if the user does not have security change access to the object after the operation. |
| `object_flags.require_full_access_after_operation` | `bool` | Requires full access to the object after the object operation. If available, the operation fails if the user does not have full access to the object after the operation. |
| `object_flags.change_acl_in_all_versions` | `bool` | Changes the ACL of all versions of the object. This is currently used to request setting the ACL of all versions of an object, not just a specific version, when calling ChangeSecurity. |
| `object_flags.verify_check_in_wopi_locked_document` | `bool` | Verify the document is locked for WOPI Co-authoring or editing during checkin. |
## Response: UpdatePropertyResponse
> 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 |
|---|---|---|
| `object_info` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The information, properties, and ACL of the modified version of the object after the operation. |
| `object_info.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `object_info.object_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_info.object_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `object_info.properties[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `object_info.properties[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
| `object_info.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.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. |
| `object_info.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `object_info.current_user_permissions.can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `object_info.current_user_permissions.can_user_edit` | `bool` | The current user can edit the object. |
| `object_info.current_user_permissions.can_user_delete` | `bool` | The current user can delete the object. |
| `object_info.current_user_permissions.can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `is_latest_visible` | `bool` | True if the latest version of the document is visible after the operation. |
| `latest_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The latest version of the object after the operation, if `is_latest_visible` is true. |
| `latest_version.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `latest_version.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `latest_version.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `latest_version.version_info.title` | `string` | The title (name) of the object in this version. |
| `latest_version.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `latest_version.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `latest_version.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `latest_version.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `latest_version.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `latest_version.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `latest_version.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `latest_version.version_info.class_id` | `int32` | The class ID of the version. |
| `latest_version.version_info.version_guid` | `string` | The GUID of this version. |
| `latest_version.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `latest_version.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `latest_version.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `latest_version.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `latest_version.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `latest_version.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `latest_version.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `latest_version.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `latest_version.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `latest_version.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `latest_version.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `latest_version.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `latest_version.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `latest_version.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `latest_version.object_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 object (e.g. is the object deleted or a stub). |
| `latest_version.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `latest_version.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `latest_version.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `latest_version.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `latest_version.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [SetProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/SetProperties/index.md): Adds, replaces or removes property values of an object.
---
# IRPCObjectOperations.UploadExistingFiles
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadExistingFiles/
Badges: `Vault API / core` `write` `session or assertion`
Copies existing file versions into new uploads, for example to create a new object with a copy
of a file.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UploadExistingFiles`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-existing-files`
- **Request:** [`UploadExistingFilesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadExistingFiles/index.md#request)
- **Response:** [`UploadExistingFilesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadExistingFiles/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Each copy is an upload like one made with
[UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) and
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md), so it can be
passed to [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md). Remove the
copies you do not use with
[RemoveUploadSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md).
## Request: UploadExistingFilesRequest
Request details for creating temporary file uploads from existing files.
> Nested 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_file_vers[]` | repeated [`ObjFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjFileVer/index.md) | The files to copy, each as object and specific file version. |
| `obj_file_vers[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_file_vers[].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_file_vers[].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_file_vers[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The specific file version, as in `File.file_ver`. |
| `obj_file_vers[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_file_vers[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_file_vers[].file_ver.internal_version` | `int32` | The file version number. |
| `obj_file_vers[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_file_vers[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `return_file_refs` | `bool` | True to get the copies in `file_refs` instead of `upload_ids`. In a vault without stateless uploads they are the upload IDs as decimal strings. |
## Response: UploadExistingFilesResponse
Response with temporary file upload ids created from existing files.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_ids[]` | repeated `int32` | An array of temporary file ids. Empty if returnFileRefs was requested. |
| `file_refs[]` | repeated `string` | If returnFileRefs was requested, the copies in the order of the requested files: file_refs of stateless uploads if the vault supports them, otherwise the upload IDs in decimal. |
## Related methods
- [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
- [UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [RemoveUploadSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RemoveUploadSession/index.md): Removes an upload and its temporary file.
---
# IRPCObjectOperations.UploadFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/
Badges: `Vault API / core` `write` `session or assertion` `idempotent`
Uploads a block of new content for an existing file of an object that is checked out to the
caller.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UploadFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-file`
- **Request:** [`UploadFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md#request)
- **Response:** [`UploadFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Works like [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): the first call has
`upload_id` 0 and `offset` 0, later calls pass the returned `upload_id`. Complete the upload with
[UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md), which replaces the
content of the file. To create a new object with files, use `UploadTempFile` and
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) instead.
## Request: UploadFileRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | 0 to start a new upload; the returned ID for the following blocks. |
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `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. |
| `file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The file to replace, as returned for the checked-out version: at least `file_ver`, and the new `size` with `size_precision` `FILE_SIZE_PRECISION_EXACT`. |
| `file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `file.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file.file_ver.internal_version` | `int32` | The file version number. |
| `file.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file.title` | `string` | The file name without the extension. |
| `file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file.guid` | `string` | GUID of the file. |
| `file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `file.is_missing` | `bool` | True, if the file is missing. |
| `file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `file.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `file.flags.can_be_edited_externally` | `bool` | Next available value. |
| `file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
| `offset` | `int64` | The position of this block in the file. Must be 0 in the first call. Use multiples of 4096 bytes for all blocks but the last. |
| `data` | `bytes` | The bytes of this block. |
## Response: UploadFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | Receives the identifier of this upload operation. |
## Related methods
- [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
- [UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md): Completes an upload made with UploadFile and stores it as the new content of the file.
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
---
# IRPCObjectOperations.UploadFileCommit
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/
Badges: `Vault API / core` `write` `session or assertion` `returns metadata structure version`
Completes an upload made with UploadFile and stores it as the new content of the file.
- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UploadFileCommit`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-file-commit`
- **Request:** [`UploadFileCommitRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md#request)
- **Response:** [`UploadFileCommitResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
The object must be checked out to the caller, and the caller needs edit access to it.
`file.size` must equal the number of bytes uploaded ("File size mismatch." otherwise) and
`file.size_precision` must be `FILE_SIZE_PRECISION_EXACT`. If `obj_id` is set, it must be the
object that owns the file ("The parameter is incorrect. (Object ID mismatch.)"). The title and
extension in `file` are ignored; rename a file with `RenameObjectFile`. The upload is removed
after the commit, also when the commit fails.
## Request: UploadFileCommitRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The ID from `UploadFile`. |
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `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. |
| `file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The file and its new size. `title` and `extension` are ignored. |
| `file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `file.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file.file_ver.internal_version` | `int32` | The file version number. |
| `file.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file.title` | `string` | The file name without the extension. |
| `file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file.guid` | `string` | GUID of the file. |
| `file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `file.is_missing` | `bool` | True, if the file is missing. |
| `file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `file.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `file.flags.can_be_edited_externally` | `bool` | Next available value. |
| `file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
| `low_digest` | `int64` | If not zero, specifies the low-order part of the MD5 checksum of the uploaded file. |
| `high_digest` | `int64` | If not zero, specifies the high-order part of the MD5 checksum of the uploaded file. |
## Response: UploadFileCommitResponse
> Nested 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_info_available` | `bool` | True if `after_upload` is filled. |
| `after_upload` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of the object after the upload, if `object_info_available` is true. |
| `after_upload.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `after_upload.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `after_upload.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `after_upload.version_info.title` | `string` | The title (name) of the object in this version. |
| `after_upload.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `after_upload.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `after_upload.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `after_upload.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `after_upload.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `after_upload.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `after_upload.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `after_upload.version_info.class_id` | `int32` | The class ID of the version. |
| `after_upload.version_info.version_guid` | `string` | The GUID of this version. |
| `after_upload.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `after_upload.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `after_upload.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `after_upload.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `after_upload.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `after_upload.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `after_upload.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `after_upload.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `after_upload.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `after_upload.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `after_upload.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `after_upload.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `after_upload.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `after_upload.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `after_upload.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `after_upload.object_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 object (e.g. is the object deleted or a stub). |
| `after_upload.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `after_upload.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `after_upload.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `after_upload.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `after_upload.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `after_upload.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.) |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [RenameObjectFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/RenameObjectFile/index.md): Renames a document file.
- [UploadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md): Uploads a block of new content for an existing file of an object that is checked out to the caller.
---
# Stateless file upload sessions (IRPCFileTransfer)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/
Stateless file upload. No method requires a sticky session.
The file_ref identifies state in Master Storage, not in an MFServer process, so any server instance
can serve any call.
The file data is sent with the hand-written client-streaming methods of IRPCFileTransferStreaming in
mfiles.filestreaming.proto, as the IDL supports only unary methods:
- FileUploadWhole: uploads a whole file in one call.
- FileUploadBlock: uploads one block between FileUploadBegin and FileUploadEnd.
- **gRPC service:** `MFiles.IRPCFileTransfer`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCFileTransfer.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCFileTransfer.proto)
## Overview
Uploads identified by a `file_ref` string instead of an upload ID. Together with
[IRPCFileTransferStreaming](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md), which carries the data,
this service is an alternative to the upload sessions of
[UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) and
[UploadFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md).
**Availability.** Stateless uploads are switched off by default in M-Files Server 26.11: every
method of this service and of `IRPCFileTransferStreaming` then answers "Not implemented.", and
[ServerVaultCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md)
`file_upload_stateless_supported` is false. Check that capability first; when it is false, upload
with [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) and
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) instead. See
[Files](https://developer.m-files.com/APIs/gRPC-API/runtime/files/index.md).
**Two ways to upload.**
- A file that fits in one storage request (see the size limit of `FileUploadWhole`):
[FileUploadWhole](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/index.md), one call.
- Any file: [FileUploadBegin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md),
[FileUploadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md) for each block, then
[FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md).
**Using the upload.** An ended upload is used by its `file_ref`: as the content of an existing file
of a checked-out object with [FileUploadAttach](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/index.md),
in the `file_ref` field of the uploaded-file sources of
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md), with
[DownloadTempFileFromUpload_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadTempFileFromUpload_Begin/index.md),
and as OCR input in [IRPCScanningAndOCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md).
**Where the upload is stored.** This depends on where the vault keeps its file data, and decides
what `FileUploadBegin` returns:
| Vault file data | `file_ref` | Blocks | Served by |
| --- | --- | --- | --- |
| Master Storage | a GUID | up to the Master Storage single request limit, any order | any server instance |
| Azure Blob Storage | a GUID | up to the Blob Storage block size (4 MiB by default), any order | any server instance |
| Disk or database | the upload ID in decimal | up to 4 MiB, in order | the server and login session that began it |
In the last case the upload is an upload session as with `UploadTempFile`: it is bound to the
login session and the server instance, and anonymous sessions cannot upload.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [FileUploadAttach](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/index.md) | Stores an ended upload as the new content of an existing file of an object that is checked out to the caller. | `write` `session or assertion` `returns metadata structure version` |
| [FileUploadBegin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md) | Begins an upload in blocks and returns its `file_ref` and the block rules. | `write` `session or assertion` |
| [FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md) | Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or AddObjectWithFiles for that. | `write` `session or assertion` |
---
# IRPCFileTransfer.FileUploadAttach
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Stores an ended upload as the new content of an existing file of an object that is checked out to
the caller.
- **Service:** [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md) `MFiles.IRPCFileTransfer`
- **gRPC method:** `/MFiles.IRPCFileTransfer/FileUploadAttach`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/file-upload-attach`
- **Request:** [`FileUploadAttachRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/index.md#request)
- **Response:** [`FileUploadAttachResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Works like [UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md): the object
must be checked out to the caller and the caller needs edit access to it. The server calculates
the MD5 checksum from the content.
`file.size` must be the exact size of the upload, with `size_precision`
`FILE_SIZE_PRECISION_EXACT` ("The size of the attached file must be exact."). Time stamps that are
not set get the current time.
An upload can be attached once. Attaching it to another file fails with "The uploaded file has
already been attached.". When the vault uses Master Storage, repeating the same attach (a retried
call) succeeds without attaching the file again.
## Request: FileUploadAttachRequest
FileUploadAttach method request structure. The server calculates the MD5 checksum of the file from the content.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_ref` | `string` | The `file_ref` of an ended upload (`FileUploadEnd` or `FileUploadWhole`). |
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. If set, it must be that object. |
| `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. |
| `file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The file to replace, with the `file_ver` of the checked-out version and the exact `size` of the upload. |
| `file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `file.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file.file_ver.internal_version` | `int32` | The file version number. |
| `file.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file.title` | `string` | The file name without the extension. |
| `file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file.guid` | `string` | GUID of the file. |
| `file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `file.is_missing` | `bool` | True, if the file is missing. |
| `file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `file.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `file.flags.can_be_edited_externally` | `bool` | Next available value. |
| `file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
## Response: FileUploadAttachResponse
> Nested 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_object_info_available` | `bool` | True if `after_upload` is filled. |
| `after_upload` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of the object after the attach, if `is_object_info_available` is true. |
| `after_upload.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `after_upload.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `after_upload.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `after_upload.version_info.title` | `string` | The title (name) of the object in this version. |
| `after_upload.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `after_upload.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `after_upload.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `after_upload.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `after_upload.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `after_upload.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `after_upload.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `after_upload.version_info.class_id` | `int32` | The class ID of the version. |
| `after_upload.version_info.version_guid` | `string` | The GUID of this version. |
| `after_upload.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `after_upload.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `after_upload.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `after_upload.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `after_upload.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `after_upload.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `after_upload.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `after_upload.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `after_upload.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `after_upload.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `after_upload.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `after_upload.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `after_upload.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `after_upload.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `after_upload.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `after_upload.object_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 object (e.g. is the object deleted or a stub). |
| `after_upload.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `after_upload.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `after_upload.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `after_upload.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `after_upload.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `after_upload.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [IRPCObjectOperations.UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md): Completes an upload made with UploadFile and stores it as the new content of the file.
---
# IRPCFileTransfer.FileUploadBegin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/
Badges: `Vault API / standard` `write` `session or assertion`
Begins an upload in blocks and returns its `file_ref` and the block rules.
- **Service:** [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md) `MFiles.IRPCFileTransfer`
- **gRPC method:** `/MFiles.IRPCFileTransfer/FileUploadBegin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/file-upload-begin`
- **Request:** [`FileUploadBeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md#request)
- **Response:** [`FileUploadBeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Upload the blocks with
[FileUploadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md), each at most
`max_block_size` bytes; all blocks but the last must be exactly `max_block_size` bytes when
`require_sequential_blocks` is true. Then call
[FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md).
A file has at most 50,000 blocks. If `total_size_in_bytes` is larger than 50,000 times the
maximum block size, the call fails with `ERROR_FILE_TOO_LARGE`. Event handlers of the vault can
cancel the upload here; the call then fails with their error.
## Request: FileUploadBeginRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `total_size_in_bytes` | `int64` | The size of the whole file in bytes, if known; 0 if not. If set, the ended upload must have exactly this size. |
## Response: FileUploadBeginResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_ref` | `string` | Identifies the upload in `FileUploadBlock`, `FileUploadEnd`, `FileUploadAttach` and the other methods that take an uploaded file. |
| `max_block_size` | `int64` | The maximum size of one block in bytes. |
| `require_sequential_blocks` | `bool` | True if the blocks must be uploaded in order, one at a time, and every block but the last must be `max_block_size` bytes. False if blocks can be uploaded in any order and concurrently, also through different server instances. |
## Related methods
- [IRPCFileTransferStreaming.FileUploadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md): Uploads one block of a stateless file upload by streaming its data.
- [FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md): Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or AddObjectWithFiles for that.
---
# IRPCFileTransfer.FileUploadEnd
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/
Badges: `Vault API / standard` `write` `session or assertion`
Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or
AddObjectWithFiles for that.
- **Service:** [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md) `MFiles.IRPCFileTransfer`
- **gRPC method:** `/MFiles.IRPCFileTransfer/FileUploadEnd`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/file-upload-end`
- **Request:** [`FileUploadEndRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md#request)
- **Response:** [`FileUploadEndResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
`block_count` must match the uploaded blocks 0..`block_count`-1 ("The block count does not match
the uploaded blocks." otherwise), and the content must have the `total_size_in_bytes` given to
`FileUploadBegin`, if any ("File size mismatch.").
## Request: FileUploadEndRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_ref` | `string` | The `file_ref` from `FileUploadBegin`. |
| `block_count` | `int64` | The number of uploaded blocks, at most 50,000. The blocks are indexes 0 to `block_count`-1. |
## Response: FileUploadEndResponse
No fields.
## Related methods
- [FileUploadBegin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md): Begins an upload in blocks and returns its `file_ref` and the block rules.
---
# Streaming file upload (IRPCFileTransferStreaming)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/
File transfer methods that stream the file data.
These methods can't be defined in the IDL, as the IDL based services support only unary methods.
- **gRPC service:** `MFiles.IRPCFileTransferStreaming`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCFileTransferStreaming.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCFileTransferStreaming.proto)
## Overview
The two methods that stream file data to the server. They belong to the `file_ref` uploads of
[IRPCFileTransfer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md); read its overview first. Like that service,
they work only when [ServerVaultCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerVaultCapabilities/index.md)
`file_upload_stateless_supported` is true; otherwise the call fails with "Not implemented.".
Stateless uploads are switched off by default in M-Files Server 26.11; upload with
[UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) and
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) there.
Both methods take a stream of request messages: one `header`, then the data as any number of
`file_data` chunks of a few megabytes at most, then one `end`. The server sends one response when
the stream is complete.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [FileUploadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md) | Uploads one block of a stateless file upload by streaming its data. | `write` `session or assertion` `client streaming` |
| [FileUploadWhole](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/index.md) | Uploads a whole file by streaming its content. | `write` `session or assertion` `client streaming` |
---
# IRPCFileTransferStreaming.FileUploadBlock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Streaming file upload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/
Badges: `Vault API / standard` `write` `session or assertion` `client streaming`
Uploads one block of a stateless file upload by streaming its data.
The file is started with FileUploadBegin, its blocks are uploaded with this method and the file is
completed with FileUploadEnd (IRPCFileTransfer). The block data is sent as a stream of chunks, so
neither the client nor the server needs to have the whole block in one message.
The client sends the messages in the following order:
1. One header message.
2. Any number of file_data messages containing the block data in order.
3. One end message.
The block is stored only when the end message has been received. If the request stream ends without
the end message, the call fails and the block must be uploaded again.
The server streams the data forward with a single request while it is received. The block
size is limited by the maxBlockSize returned by FileUploadBegin. Blocks may be uploaded in any order and
concurrently, also to different server instances. Uploading a block again replaces it.
The data should be sent in chunks of a few megabytes at most. Each file_data message is limited by the
maximum gRPC message size of the server.
- **Service:** [Streaming file upload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md) `MFiles.IRPCFileTransferStreaming`
- **gRPC method:** `/MFiles.IRPCFileTransferStreaming/FileUploadBlock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/file-upload-block`
- **Request:** [`FileUploadBlockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md#request)
- **Response:** [`FileUploadBlockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** client
## Remarks
Begin the upload with [FileUploadBegin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md) and
follow its `max_block_size` and `require_sequential_blocks`. A block index must be less than
50,000 and a block must not be empty.
## Request: FileUploadBlockRequest
A message of the FileUploadBlock request stream.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `header` | [`FileUploadBlockHeader`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileUploadBlockHeader/index.md) (oneof item) | The first message of the stream. Describes the block. |
| `header.file_ref` | `string` | The file_ref received from FileUploadBegin. |
| `header.block_index` | `int64` | The zero-based index of the block within the file, in content order. Must be less than 50 000. |
| `header.block_size` | `uint64` | The size of the block data in bytes. Required.
The data must be exactly this size and must not exceed the maxBlockSize returned by FileUploadBegin. |
| `file_data` | `bytes` (oneof item) | A chunk of the block data. |
| `end` | [`FileUploadBlockEnd`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileUploadBlockEnd/index.md) (oneof item) | The last message of the stream. Marks the block as complete. |
## Response: FileUploadBlockResponse
The response of the FileUploadBlock streaming method.
No fields.
## Related methods
- [IRPCFileTransfer.FileUploadBegin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md): Begins an upload in blocks and returns its `file_ref` and the block rules.
---
# IRPCFileTransferStreaming.FileUploadWhole
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Streaming file upload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/
Badges: `Vault API / standard` `write` `session or assertion` `client streaming`
Uploads a whole file by streaming its content.
The content is sent as a stream of chunks, so neither the client nor the server needs to have the
whole content in one message.
The client sends the messages in the following order:
1. One header message.
2. Any number of file_data messages containing the file content in order.
3. One end message.
The upload is complete only when the end message has been received. If the request stream ends
without the end message, the upload is discarded.
The server streams the content forward with a single request while it is received, so the
size of the file is limited by the maximum size of content Master Storage accepts in a single request
(the MaxSingleOperationBlobSize setting, 25 MiB by default). The call fails with ERROR_FILE_TOO_LARGE
before any content is stored if the declared size exceeds the limit. Larger files must be uploaded in
blocks with FileUploadBegin, FileUploadBlock and FileUploadEnd.
The content should be sent in chunks of a few megabytes at most. Each file_data message is limited by
the maximum gRPC message size of the server.
- **Service:** [Streaming file upload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/index.md) `MFiles.IRPCFileTransferStreaming`
- **gRPC method:** `/MFiles.IRPCFileTransferStreaming/FileUploadWhole`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/file-upload-whole`
- **Request:** [`FileUploadWholeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/index.md#request)
- **Response:** [`FileUploadWholeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadWhole/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** client
## Remarks
Without `obj_id` and `file` in the header, the result is an ended upload that you use by its
`file_ref`, for example in
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) or
[FileUploadAttach](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/index.md). With both, the content is
attached to that file right away, as with `FileUploadAttach`, so the object must be checked out to
the caller.
## Request: FileUploadWholeRequest
A message of the FileUploadWhole request stream.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `header` | [`FileUploadWholeHeader`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileUploadWholeHeader/index.md) (oneof item) | The first message of the stream. Describes the upload. |
| `header.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The id of the object to which the file is bound, if attaching immediately.
If set, together with file, attach the content to this object's file immediately. If not set, the content is only stored as a stateless temp file, retrievable later via the returned file_ref, using a separate FileUploadAttach call. obj_id and file must either both be set or both be omitted. |
| `header.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). |
| `header.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`. |
| `header.file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | Information about the uploaded file, if attaching immediately. |
| `header.file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `header.file.title` | `string` | The file name without the extension. |
| `header.file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `header.file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `header.file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `header.file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `header.file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `header.file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `header.file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `header.file.guid` | `string` | GUID of the file. |
| `header.file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `header.file.is_missing` | `bool` | True, if the file is missing. |
| `header.file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `header.file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `header.file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
| `header.file_size` | `uint64` | The size of the whole file content in bytes. Required.
The content must be exactly this size. Zero means an empty file. The server uses the size to reject a file that exceeds the maximum upload size before any content is sent, and to stream the content forward as it is received. |
| `file_data` | `bytes` (oneof item) | A chunk of the file content. |
| `end` | [`FileUploadWholeEnd`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileUploadWholeEnd/index.md) (oneof item) | The last message of the stream. Marks the upload as complete. |
## Response: FileUploadWholeResponse
The response of the FileUploadWhole streaming 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 |
|---|---|---|
| `file_ref` | `string` | The file_ref identifier of the now-ended content.
If obj_id and file were not supplied, the content can be attached later with FileUploadAttach. If they were supplied, the content has already been attached and the file_ref can't be attached to another file. |
| `is_object_info_available` | `bool` | True if information about the object after the attach was provided.
Always false if obj_id and file were not supplied, or if the user can't see the object after the attach. |
| `after_upload` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | If is_object_info_available is true, information about the object after the attach. |
| `after_upload.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `after_upload.version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `after_upload.version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `after_upload.version_info.title` | `string` | The title (name) of the object in this version. |
| `after_upload.version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `after_upload.version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `after_upload.version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `after_upload.version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `after_upload.version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `after_upload.version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `after_upload.version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `after_upload.version_info.class_id` | `int32` | The class ID of the version. |
| `after_upload.version_info.version_guid` | `string` | The GUID of this version. |
| `after_upload.version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `after_upload.version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `after_upload.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `after_upload.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `after_upload.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `after_upload.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `after_upload.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `after_upload.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `after_upload.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `after_upload.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `after_upload.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `after_upload.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `after_upload.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `after_upload.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `after_upload.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `after_upload.object_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 object (e.g. is the object deleted or a stub). |
| `after_upload.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `after_upload.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `after_upload.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `after_upload.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `after_upload.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `after_upload.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Information about objects that were also updated during the operation. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
## Related methods
- [IRPCObjectOperations.AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.
- [IRPCFileTransfer.FileUploadAttach](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadAttach/index.md): Stores an ended upload as the new content of an existing file of an object that is checked out to the caller.
---
# Views (IRPCViews)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/
Reads and maintains the views of the vault: the common views and the calling user's own
(private) views.
All view operations can be done via this interface.
MFClient uses this interface to manage the user-specific view collection and common
view collection.
- **gRPC service:** `MFiles.IRPCViews`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 14
- **Proto file:** [`mfiles/IRPCViews.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCViews.proto)
## Overview
A view is a saved search with optional grouping levels, shown as a folder in M-Files clients.
**Common views** are defined by administrators and are visible to the users their ACL allows.
**Private views** belong to one user. Every user has a view collection: the common views they
may see plus their own private views, each with a per-user visible or hidden flag. For the
search side of views, see
[Search](https://developer.m-files.com/APIs/gRPC-API/concepts/search/index.md).
- **Read the view collection**:
[GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md) (all views, or the children of one view),
[GetViewsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md) (keep a local copy up to date),
[GetView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/index.md) (one view).
- **Create and change views**: [AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md),
[ModifyView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/ModifyView/index.md),
[DeleteView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DeleteView/index.md),
[SetViewVisibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/index.md) (per user).
- **Share a private view** with another user:
[EnableShareView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md) by the owner, then
[CopyView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/index.md) by the recipient.
- **External repositories**: [GetMultipleViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetMultipleViews/index.md) and
[GetExternalRepositoryIcons](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetExternalRepositoryIcons/index.md).
- **Traditional folders in a view**: [CreateSubFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CreateSubFolder/index.md).
To list the objects in a view, search with the view's `content_definition`, or browse it with
the folder content methods of [IRPCSearch](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md).
**Rights.** Reading needs no special vault rights. Creating or changing private views needs the
vault right `manage_private_views`; creating, changing or deleting common views needs
`manage_common_views`; making a view indexed needs `materialize_views`
([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)). Anonymous sessions cannot create or delete views.
**Built-in views.** Every vault has built-in views with fixed IDs, for example 5 Checked Out to
Me, 7 Recently Modified by Me, 9 Assigned to Me, 14 Recently Accessed by Me and 15 Favorites.
Some of them are hidden by default (for example 12 and 18 ID views, 13 Built-in, 16 Reports,
17 Conflicts, 23 All object types). Built-in views cannot be deleted, and most of them cannot
be changed.
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md) | Gets the calling user's view collection: all views, or the direct child views of one view. | `write` `session or assertion` `returns metadata structure version` |
| [GetView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/index.md) | Gets one view of the calling user's view collection, or one external view, as folder data. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetViewsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md) | Gets the calling user's whole view collection, or only the changes since a version the caller already has. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md) | Creates a new private or common view. | `write` `session or assertion` `returns metadata structure version` |
| [CopyView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/index.md) | Copies a private view that another user has shared, with its child views, into the caller's own views. | `write` `session or assertion` `returns metadata structure version` |
| [CreateSubFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CreateSubFolder/index.md) | Creates a traditional folder at a location inside a view, or returns an existing folder with the same name there. | `write` `session or assertion` `returns metadata structure version` |
| [DeleteView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DeleteView/index.md) | Deletes a view and its child views. | `write` `session or assertion` `returns metadata structure version` |
| [DownloadFolderContentWithDownloadKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DownloadFolderContentWithDownloadKey/index.md) | Not available: always fails with "Not implemented.". | `write` `session or assertion` |
| [EnableShareView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md) | Allows other users to copy the given private views of the caller for a limited time. | `write` `session or assertion` `returns metadata structure version` |
| [GetExternalRepositoryIcons](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetExternalRepositoryIcons/index.md) | Gets icons that external repository connections provide for their views and objects. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetFolderContentDownloadUrl](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetFolderContentDownloadUrl/index.md) | Not available: always fails with "Not implemented.". | `write` `session or assertion` |
| [GetMultipleViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetMultipleViews/index.md) | Gets several views of external repositories in one call. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [ModifyView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/ModifyView/index.md) | Replaces the definition of an existing view. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [SetViewVisibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/index.md) | Shows or hides a view in the calling user's view collection. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
---
# IRPCViews.GetViews
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Gets the calling user's view collection: all views, or the direct child views of one view.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/GetViews`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-views`
- **Request:** [`GetViewsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md#request)
- **Response:** [`GetViewsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed. Common views that the user may
not see and other users' private views are left out.
- Hidden views are included; check `View.is_visible`.
- With `get_all_views` false, set `parent_view`: -1 returns the top-level views. The default 0
is not the top level and returns nothing.
- The order of the views is not specified. Lookup values in search conditions are returned in
the session's vault language.
- To keep a local copy in sync, use [GetViewsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md)
instead.
## Request: GetViewsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `get_all_views` | `bool` | True to get every view in the user's collection. Then `parent_view` is ignored. |
| `parent_view` | `int32` | With `get_all_views` false, the ID of the view whose direct child views to get, or -1 for the top-level views. |
## Response: GetViewsResponse
> 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 |
|---|---|---|
| `views[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The views. See [View](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md). |
| `views[].id` | `int32` | The ID of the view. |
| `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). |
| `views[].name` | `string` | The name of the view. |
| `views[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `views[].is_visible` | `bool` | Tells if the view is visible. |
| `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. |
| `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. |
| `views[].location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `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. |
| `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. |
| `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. |
| `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). |
| `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. |
| `views[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `views[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `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. |
| `views[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `views[].options.indexed` | `bool` | Materialized/indexed view. |
| `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. |
| `views[].options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `views[].guid` | `string` | GUID for the view. |
| `views[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `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. |
## Related methods
- [GetViewsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md): Gets the calling user's whole view collection, or only the changes since a version the caller already has.
---
# IRPCViews.GetView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/
Badges: `Vault API / standard` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets one view of the calling user's view collection, or one external view, as folder data.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/GetView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-view`
- **Request:** [`GetViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/index.md#request)
- **Response:** [`GetViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- For a vault view, set `view_id.internal_id` and set `required_folder_info.folder_info` to true;
without it the call fails with "The parameter is incorrect.". Requiring `location` fails with
"Not implemented.".
- The response holds the view in `putf8szview.data.view_folder.view`.
- A view that is not in the user's collection, such as another user's private view, fails with
"Not found.".
- For a view of an external repository, set `view_id.external_repository_id` instead.
## Request: GetViewRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The view: `internal_id` for a vault view, or `external_repository_id` for an external view. |
| `view_id.internal_id` | `int32` | The ID of the object or value list item. |
| `view_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. |
| `view_id.external_repository_id.connection` | `string` | The external repository connection identifier. |
| `view_id.external_repository_id.item` | `string` | External ID within the scope of the connection to external system. |
| `required_folder_info` | [`FOLDERDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERDATAREQUESTFLAGS/index.md) | The folder information that must be returned. For a vault view, set `folder_info`. |
| `required_folder_info.all` | `bool` | Specifies all flags set; Including any future flags. |
| `required_folder_info.folder_info` | `bool` | Folder information is requested, e.g. View or ExternalView. |
| `required_folder_info.location` | `bool` | The exact location of the folder is requested, e.g. ViewLocation or FolderArray. |
| `required_folder_info.acl` | `bool` | The acl of the folder is requested. |
| `accepted_folder_info` | [`FOLDERDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERDATAREQUESTFLAGS/index.md) | Additional folder information the caller can accept. Used for external views. |
| `accepted_folder_info.all` | `bool` | Specifies all flags set; Including any future flags. |
| `accepted_folder_info.folder_info` | `bool` | Folder information is requested, e.g. View or ExternalView. |
| `accepted_folder_info.location` | `bool` | The exact location of the folder is requested, e.g. ViewLocation or FolderArray. |
| `accepted_folder_info.acl` | `bool` | The acl of the folder is requested. |
## Response: GetViewResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `putf8szview` | [`FolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderData/index.md) | The view as [FolderData](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderData/index.md). |
| `putf8szview.type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder (eg. eftViewFolder). Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `putf8szview.data` | [`FolderDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderDataUnion/index.md) | Additional folder type -specific data as a union. |
| `putf8szview.data.view_folder` | [`FolderDataUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderDataUnion/index.md#t-ViewFolderData) (oneof data) | |
| `putf8szview.data.external_view_folder` | [`FolderDataUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderDataUnion/index.md#t-ExternalViewFolderData) (oneof data) | |
| `putf8szview.folder_location` | [`FolderArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderArray/index.md) | Array of folders describing the exact location of the folder. If null, the caller must resolve the location by walking the parent chain. |
| `putf8szview.folder_location.value[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Array of Folder structures. |
| `putf8szview.folder_location_name` | `string` | The display name of the folder location. Describes the location (e.g. full path) rather than the actual name. Specified only if the location data is specified, too. |
---
# IRPCViews.GetViewsOrDelta
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/
Badges: `Vault API / standard` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the calling user's whole view collection, or only the changes since a version the caller
already has.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/GetViewsOrDelta`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-views-or-delta`
- **Request:** [`GetViewsOrDeltaRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md#request)
- **Response:** [`GetViewsOrDeltaResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- First call with `callers_current_views_version` 0: `views_or_delta.type` is false (a full
list) and `current_views_version_on_server` is the version to store.
- Later, send the stored version back:
- nothing changed: the same version comes back with `type` true and empty lists;
- something changed: `type` true; `views` has the added and changed views, `removed_views` the
IDs of deleted views, and `invisible_views` the IDs of views the user can no longer see. Then
store the new version.
- A version newer than the server's (for example from another vault) returns the full list and
the server's current version.
- Hiding or showing a view with
[SetViewVisibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/index.md) also produces a change.
- When a deleted view had child views, only the parent's ID appears in `removed_views`; remove
its descendants from your copy too.
## Request: GetViewsOrDeltaRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `callers_current_views_version` | `int64` | The `current_views_version_on_server` from the caller's previous response, or 0 to get the full collection. |
## Response: GetViewsOrDeltaResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `current_views_version_on_server` | `int64` | The version of the view collection now. Store it and send it next time. |
| `views_or_delta` | [`ViewsOrDeltaEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewsOrDeltaEx/index.md) | The full collection (`type` false) or the changes (`type` true). See [ViewsOrDeltaEx](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewsOrDeltaEx/index.md). |
| `views_or_delta.type` | `bool` | True if this struct represents a delta (i.e. just the occurred changes to views). |
| `views_or_delta.removed_views[]` | repeated `int32` | Removed views. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
| `views_or_delta.invisible_views[]` | repeated `int32` | Invisible views. This contains data only when this struct represents a delta. Otherwise it must be an empty array. |
| `views_or_delta.views[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | Views. This contains inserted or updated views if this struct represents a delta, otherwise it contains just a "normal" array of views. |
| `views_or_delta.views[].id` | `int32` | The ID of the view. |
| `views_or_delta.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). |
| `views_or_delta.views[].name` | `string` | The name of the view. |
| `views_or_delta.views[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `views_or_delta.views[].is_visible` | `bool` | Tells if the view is visible. |
| `views_or_delta.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. |
| `views_or_delta.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. |
| `views_or_delta.views[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `views_or_delta.views[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `views_or_delta.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. |
| `views_or_delta.views[].guid` | `string` | GUID for the view. |
| `views_or_delta.views[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
## Related methods
- [SetViewVisibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/index.md): Shows or hides a view in the calling user's view collection.
- [GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md): Gets the calling user's view collection: all views, or the direct child views of one view.
---
# IRPCViews.AddNewView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Creates a new private or common view.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/AddNewView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-new-view`
- **Request:** [`AddNewViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md#request)
- **Response:** [`AddNewViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- **Private view** (`is_common` false): requires the vault right `manage_private_views`. The
server replaces the ACL you send with one that gives all internal users read access; only the
owner sees the view anyway.
- **Common view** (`is_common` true): requires `manage_common_views` and an explicit `acl`
without named ACL references; an empty ACL fails with "The parameter is incorrect. (Zero
length ACL.)".
- The server assigns `id` and `guid`; the values you send are ignored. The response has the
stored view.
- Names must be unique, ignoring case, among the common views and the user's own views at the
same level; a duplicate fails with "Another view with the same name already exists.".
- To place the view inside another view, set `location`. A common view needs a common parent,
and a private view's parent must be a common view or one of the user's own views. Views cannot
be added under the built-in views 13 (Built-in) and 23 (All object types).
- Indexed views (`options.indexed`) need `materialize_views`, cannot be private and cannot be
filter-only views.
- Vault event handlers for views run. Anonymous sessions get "Access denied.".
## Request: AddNewViewRequest
> 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 |
|---|---|---|
| `utf8szview` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The new view. Set at least `name`, `type`, `is_common`, `is_visible` and `content_definition`; for a common view also `acl`. `id` and `guid` are ignored. |
| `utf8szview.id` | `int32` | The ID of the view. |
| `utf8szview.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). |
| `utf8szview.name` | `string` | The name of the view. |
| `utf8szview.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `utf8szview.is_visible` | `bool` | Tells if the view is visible. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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). |
| `utf8szview.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. |
| `utf8szview.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `utf8szview.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. |
| `utf8szview.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `utf8szview.options.indexed` | `bool` | Materialized/indexed view. |
| `utf8szview.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. |
| `utf8szview.options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `utf8szview.guid` | `string` | GUID for the view. |
| `utf8szview.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `utf8szview.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. |
## Response: AddNewViewResponse
> 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_view` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The view as stored, with its new ID and GUID. |
| `new_view.id` | `int32` | The ID of the view. |
| `new_view.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). |
| `new_view.name` | `string` | The name of the view. |
| `new_view.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `new_view.is_visible` | `bool` | Tells if the view is visible. |
| `new_view.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. |
| `new_view.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. |
| `new_view.location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `new_view.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. |
| `new_view.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. |
| `new_view.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. |
| `new_view.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). |
| `new_view.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. |
| `new_view.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `new_view.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_view.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_view.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_view.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_view.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_view.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_view.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `new_view.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. |
| `new_view.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `new_view.options.indexed` | `bool` | Materialized/indexed view. |
| `new_view.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. |
| `new_view.options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `new_view.guid` | `string` | GUID for the view. |
| `new_view.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `new_view.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. |
---
# IRPCViews.CopyView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Copies a private view that another user has shared, with its child views, into the caller's
own views.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/CopyView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/copy-view`
- **Request:** [`CopyViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/index.md#request)
- **Response:** [`CopyViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- The owner must first share the view with
[EnableShareView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md). Otherwise the call fails with
"This view is not shared with you.". The sharing expires after the number of days that
[EnableShareView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md) returns (14 by default).
- Common views cannot be copied.
- The copy is a new private view at the top level of the caller's views; its child views are
copied with it. Vault event handlers for views run.
## Request: CopyViewRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the shared view (`internal_id`). |
| `view_id.internal_id` | `int32` | The ID of the object or value list item. |
| `view_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. |
| `view_id.external_repository_id.connection` | `string` | The external repository connection identifier. |
| `view_id.external_repository_id.item` | `string` | External ID within the scope of the connection to external system. |
## Response: CopyViewResponse
> 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 |
|---|---|---|
| `putf8szviews[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The new view and its copied child views. |
| `putf8szviews[].id` | `int32` | The ID of the view. |
| `putf8szviews[].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). |
| `putf8szviews[].name` | `string` | The name of the view. |
| `putf8szviews[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `putf8szviews[].is_visible` | `bool` | Tells if the view is visible. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].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). |
| `putf8szviews[].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. |
| `putf8szviews[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].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. |
| `putf8szviews[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `putf8szviews[].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. |
| `putf8szviews[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `putf8szviews[].options.indexed` | `bool` | Materialized/indexed view. |
| `putf8szviews[].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. |
| `putf8szviews[].options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `putf8szviews[].guid` | `string` | GUID for the view. |
| `putf8szviews[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `putf8szviews[].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. |
## Related methods
- [EnableShareView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md): Allows other users to copy the given private views of the caller for a limited time.
---
# IRPCViews.CreateSubFolder
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CreateSubFolder/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Creates a traditional folder at a location inside a view, or returns an existing folder with
the same name there.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/CreateSubFolder`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-sub-folder`
- **Request:** [`CreateSubFolderRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CreateSubFolder/index.md#request)
- **Response:** [`CreateSubFolderResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CreateSubFolder/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- `view_location.parent_folder` must not be empty, and `subfolder` must not have a parent
folder; otherwise the call fails with "The parameter is incorrect.".
- Only works at locations that allow traditional folders; elsewhere it fails with "Sorry, but
it's not possible to create traditional folders here.".
- If a folder with the same name exists at the location, it is returned instead of a new one.
- Related: [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md)
creates folders outside view locations.
## Request: CreateSubFolderRequest
Requests to create a sub-folder.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `view_location` | [`ViewLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewLocation/index.md) | The location in the view: `parent_folder` starts with the view folder. |
| `view_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. |
| `view_location.parent_folder[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `view_location.parent_folder[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `view_location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `view_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. |
| `view_location.customized_property_folder.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `view_location.customized_property_folder.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `view_location.customized_property_folder.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. |
| `subfolder` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The folder to create: `item_info.obj_id.type` 4 (Traditional folders) and `item_info.name`. The item ID is ignored. |
| `subfolder.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. |
| `subfolder.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. |
| `subfolder.item_info.name` | `string` | The name of the item. |
| `subfolder.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). |
| `subfolder.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. |
| `subfolder.item_info.guid` | `string` | GUID for the item. |
| `subfolder.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). |
| `subfolder.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `subfolder.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `subfolder.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `subfolder.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `subfolder.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `subfolder.owner_name` | `string` | The name of the owner item. |
| `subfolder.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. |
| `subfolder.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. |
| `subfolder.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. |
| `subfolder.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `subfolder.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. |
| `subfolder.icon.value` | `bytes` | Array of bytes. |
## Response: CreateSubFolderResponse
Response to create sub-folder 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 |
|---|---|---|
| `folder` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The created or found folder. |
| `folder.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. |
| `folder.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. |
| `folder.item_info.name` | `string` | The name of the item. |
| `folder.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). |
| `folder.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. |
| `folder.item_info.guid` | `string` | GUID for the item. |
| `folder.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). |
| `folder.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `folder.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `folder.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `folder.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `folder.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `folder.owner_name` | `string` | The name of the owner item. |
| `folder.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. |
| `folder.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. |
| `folder.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. |
| `folder.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `folder.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. |
| `folder.icon.value` | `bytes` | Array of bytes. |
| `value_list_version` | `int64` | The current version of the Traditional folders list's items. |
## Related methods
- [IRPCValueLists.CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md): Creates a traditional folder, or returns an existing folder with the same name.
---
# IRPCViews.DeleteView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DeleteView/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Deletes a view and its child views.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/DeleteView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/delete-view`
- **Request:** [`DeleteViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DeleteView/index.md#request)
- **Response:** [`DeleteViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DeleteView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Common views need `manage_common_views`; otherwise the call fails with "Deleting a common view
is not allowed.". A private view can be deleted only by its owner ("Access denied." for
others).
- Child views are deleted too, including other users' private child views of a common view.
- Built-in views cannot be deleted. Anonymous sessions get "Access denied.".
- Deleting a view that does not exist, or was already deleted, succeeds and does nothing.
- The view appears in `removed_views` of
[GetViewsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md). Vault event handlers for views
run.
## Request: DeleteViewRequest
> Nested 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 view to delete. |
## Response: DeleteViewResponse
No fields.
## Related methods
- [GetViewsOrDelta](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViewsOrDelta/index.md): Gets the calling user's whole view collection, or only the changes since a version the caller already has.
---
# IRPCViews.DownloadFolderContentWithDownloadKey
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DownloadFolderContentWithDownloadKey/
Badges: `Vault API / standard` `write` `session or assertion`
Not available: always fails with "Not implemented.".
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/DownloadFolderContentWithDownloadKey`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-folder-content-with-download-key`
- **Request:** [`DownloadFolderContentWithDownloadKeyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DownloadFolderContentWithDownloadKey/index.md#request)
- **Response:** [`DownloadFolderContentWithDownloadKeyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/DownloadFolderContentWithDownloadKey/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: DownloadFolderContentWithDownloadKeyRequest
> Nested 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_key` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | Contains identifier that will be used to locate the folder contents. |
| `download_key.value` | `string` | String. |
## Response: DownloadFolderContentWithDownloadKeyResponse
No fields.
---
# IRPCViews.EnableShareView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Allows other users to copy the given private views of the caller for a limited time.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/EnableShareView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/enable-share-view`
- **Request:** [`EnableShareViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md#request)
- **Response:** [`EnableShareViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/EnableShareView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Only the caller's own private views can be shared; another user's view or a common view fails
with "Access denied.".
- Sharing starts now and lasts the returned number of days. Calling again restarts the period.
- Other users take a copy with [CopyView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/index.md); the original view
stays private.
## Request: EnableShareViewRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `views_count` | `uint32` | The number of entries in `shared_views`. Must match. |
| `shared_views[]` | repeated [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The IDs (`internal_id`) of the views to share. |
| `shared_views[].internal_id` | `int32` | The ID of the object or value list item. |
| `shared_views[].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. |
| `shared_views[].external_repository_id.connection` | `string` | The external repository connection identifier. |
| `shared_views[].external_repository_id.item` | `string` | External ID within the scope of the connection to external system. |
## Response: EnableShareViewResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `sharing_days` | `int32` | How many days other users can copy the views, as set by the vault administrator (14 by default). |
## Related methods
- [CopyView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/CopyView/index.md): Copies a private view that another user has shared, with its child views, into the caller's own views.
---
# IRPCViews.GetExternalRepositoryIcons
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetExternalRepositoryIcons/
Badges: `Vault API / standard` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets icons that external repository connections provide for their views and objects.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/GetExternalRepositoryIcons`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-repository-icons`
- **Request:** [`GetExternalRepositoryIconsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetExternalRepositoryIcons/index.md#request)
- **Response:** [`GetExternalRepositoryIconsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetExternalRepositoryIcons/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. The icons are requested from the external repository connections
of the vault. An empty `ids` list fails with "Not found.".
- Each result carries its `id`, so you can match results to requests.
## Request: GetExternalRepositoryIconsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ids[]` | repeated [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The icon IDs: the external repository connection and the icon's ID within it. |
| `ids[].connection` | `string` | The external repository connection identifier. |
| `ids[].item` | `string` | External ID within the scope of the connection to external system. |
| `icon_format` | [`IconFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.IconFormat/index.md) | `ICON_FORMAT_ICO` for a multi-size .ico file, or `ICON_FORMAT_PNG` for a PNG image of `size` pixels. Values: `ICON_FORMAT_ICO` (0), `ICON_FORMAT_PNG` (1). |
| `size` | `int32` | With `ICON_FORMAT_PNG`, the width and height of the image in pixels. Ignored for `ICON_FORMAT_ICO`. |
## Response: GetExternalRepositoryIconsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `icons[]` | repeated [`ExternalRepositoryIcon`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryIcon/index.md) | The icons; see [ExternalRepositoryIcon](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryIcon/index.md). |
| `icons[].id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | The icon ID (external repository name and icon ID). |
| `icons[].id.connection` | `string` | The external repository connection identifier. |
| `icons[].id.item` | `string` | External ID within the scope of the connection to external system. |
| `icons[].data` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | The icon as an .ICO file byte presentation. |
| `icons[].data.value` | `bytes` | Array of bytes. |
---
# IRPCViews.GetFolderContentDownloadUrl
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetFolderContentDownloadUrl/
Badges: `Vault API / standard` `write` `session or assertion`
Not available: always fails with "Not implemented.".
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/GetFolderContentDownloadUrl`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-content-download-url`
- **Request:** [`GetFolderContentDownloadUrlRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetFolderContentDownloadUrl/index.md#request)
- **Response:** [`GetFolderContentDownloadUrlResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetFolderContentDownloadUrl/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetFolderContentDownloadUrlRequest
Request details for generating a download key for downloading contents of multiple folders.
> Nested 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_requests[]` | repeated [`FolderContentDownloadUrlRequestData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderContentDownloadUrlRequestData/index.md) | Download requests. |
| `download_requests[].folders[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Array of folders defining the folder contents to download. |
| `download_requests[].folders[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `download_requests[].folders[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
## Response: GetFolderContentDownloadUrlResponse
Response details for generating a download key for downloading contents of multiple folders.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `url` | `string` | The download URL. |
---
# IRPCViews.GetMultipleViews
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetMultipleViews/
Badges: `Vault API / standard` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets several views of external repositories in one call.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/GetMultipleViews`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-multiple-views`
- **Request:** [`GetMultipleViewsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetMultipleViews/index.md#request)
- **Response:** [`GetMultipleViewsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetMultipleViews/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Only for external repository views: every ID must have `external_repository_id` set. A vault
view ID fails the call with "The parameter is incorrect."; read vault views with
[GetView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/index.md) or [GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md).
- The views are requested from the external repository connections of the vault.
## Request: GetMultipleViewsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `utf8szviewids[]` | repeated [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The IDs of the external views, each with `external_repository_id` set. |
| `utf8szviewids[].internal_id` | `int32` | The ID of the object or value list item. |
| `utf8szviewids[].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. |
| `utf8szviewids[].external_repository_id.connection` | `string` | The external repository connection identifier. |
| `utf8szviewids[].external_repository_id.item` | `string` | External ID within the scope of the connection to external system. |
| `required` | [`FOLDERDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERDATAREQUESTFLAGS/index.md) | The folder information that must be returned. |
| `required.all` | `bool` | Specifies all flags set; Including any future flags. |
| `required.folder_info` | `bool` | Folder information is requested, e.g. View or ExternalView. |
| `required.location` | `bool` | The exact location of the folder is requested, e.g. ViewLocation or FolderArray. |
| `required.acl` | `bool` | The acl of the folder is requested. |
| `accepted` | [`FOLDERDATAREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERDATAREQUESTFLAGS/index.md) | Additional folder information the caller can accept. |
| `accepted.all` | `bool` | Specifies all flags set; Including any future flags. |
| `accepted.folder_info` | `bool` | Folder information is requested, e.g. View or ExternalView. |
| `accepted.location` | `bool` | The exact location of the folder is requested, e.g. ViewLocation or FolderArray. |
| `accepted.acl` | `bool` | The acl of the folder is requested. |
## Response: GetMultipleViewsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `putf8szviews[]` | repeated [`FolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderData/index.md) | The views as [FolderData](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderData/index.md). |
| `putf8szviews[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder (eg. eftViewFolder). Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `putf8szviews[].data` | [`FolderDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderDataUnion/index.md) | Additional folder type -specific data as a union. |
| `putf8szviews[].data.view_folder` | [`FolderDataUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderDataUnion/index.md#t-ViewFolderData) (oneof data) | |
| `putf8szviews[].data.external_view_folder` | [`FolderDataUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderDataUnion/index.md#t-ExternalViewFolderData) (oneof data) | |
| `putf8szviews[].folder_location` | [`FolderArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderArray/index.md) | Array of folders describing the exact location of the folder. If null, the caller must resolve the location by walking the parent chain. |
| `putf8szviews[].folder_location.value[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Array of Folder structures. |
| `putf8szviews[].folder_location_name` | `string` | The display name of the folder location. Describes the location (e.g. full path) rather than the actual name. Specified only if the location data is specified, too. |
## Related methods
- [GetView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetView/index.md): Gets one view of the calling user's view collection, or one external view, as folder data.
- [GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md): Gets the calling user's view collection: all views, or the direct child views of one view.
---
# IRPCViews.ModifyView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/ModifyView/
Badges: `Vault API / standard` `write` `session or assertion` `idempotent` `returns metadata structure version`
Replaces the definition of an existing view.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/ModifyView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-view`
- **Request:** [`ModifyViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/ModifyView/index.md#request)
- **Response:** [`ModifyViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/ModifyView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Send the complete view, identified by `id`: read it first, change what you need and send it
back.
- Private views need `manage_private_views`; common views (or turning a common view into a
private one, or the other way round) need `manage_common_views`. Only the owner can modify a
private view; for other users it fails with "Not found.".
- Some built-in views cannot be changed at all, for example 12, 13, 15, 16, 17, 18 and 23. Of
the views under Built-in (13) only the name and ACL can be changed, and of the views under
All object types (23) only the visualization.
- If the grouping levels change, child views that are inside the grouping levels are deleted.
- A common view can be made private only if all its child views are the caller's own private
views.
- The duplicate-name and indexing rules of [AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md)
apply. Vault event handlers for views run.
## Request: ModifyViewRequest
> 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 |
|---|---|---|
| `utf8szview` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The complete new definition of the view, with the `id` of the view to change. |
| `utf8szview.id` | `int32` | The ID of the view. |
| `utf8szview.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). |
| `utf8szview.name` | `string` | The name of the view. |
| `utf8szview.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `utf8szview.is_visible` | `bool` | Tells if the view is visible. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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). |
| `utf8szview.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. |
| `utf8szview.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.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. |
| `utf8szview.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `utf8szview.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. |
| `utf8szview.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `utf8szview.options.indexed` | `bool` | Materialized/indexed view. |
| `utf8szview.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. |
| `utf8szview.options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `utf8szview.guid` | `string` | GUID for the view. |
| `utf8szview.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `utf8szview.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. |
## Response: ModifyViewResponse
No fields.
## Related methods
- [AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md): Creates a new private or common view.
---
# IRPCViews.SetViewVisibility
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/
Badges: `Vault API / standard` `write` `session or assertion` `idempotent` `returns metadata structure version`
Shows or hides a view in the calling user's view collection.
- **Service:** [Views](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md) `MFiles.IRPCViews`
- **gRPC method:** `/MFiles.IRPCViews/SetViewVisibility`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-view-visibility`
- **Request:** [`SetViewVisibilityRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/index.md#request)
- **Response:** [`SetViewVisibilityResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/SetViewVisibility/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Affects only the calling user: hiding a common view does not hide it from other users. No
special vault rights are needed.
- Works for common views and for the user's own private views. Hidden views are still returned
by [GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md), with `is_visible` false.
## Request: SetViewVisibilityRequest
> Nested 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 view. |
| `visible` | `bool` | True to show the view, false to hide it. |
## Response: SetViewVisibilityResponse
No fields.
## Related methods
- [GetViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/GetViews/index.md): Gets the calling user's view collection: all views, or the direct child views of one view.
---
# Server push (IRPCServerDataPush)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/
A server-to-client channel: the server pushes requests and notifications to a logged-in client
over a long-lived stream.
- **gRPC service:** `MFiles.IRPCServerDataPush`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCServerDataPush.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCServerDataPush.proto)
## Overview
Some operations need something from the user while the server is processing a call, for
example an electronic signature for a workflow state transition, or credentials for a vault
application or external repository. The server asks for it over the push channel of the
session, and the client answers with a separate call. M-Files clients use this service;
applications that perform such operations interactively need it too.
**Lifecycle**
1. Log in, then call [OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md)
with the session's `mfiles-session-id-bin` metadata. It is a server-streaming call that stays
open, without messages, until the server has something to push. Do not set a short deadline
on it. Session assertions are not accepted.
2. Each session has at most one channel. Opening a new one ends the previous stream with status
`OK`. Logging out also ends the stream with `OK`. If the stream ends while the session is
still valid, open it again.
3. Each message is a [ServerDataPushItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md#response). Its
`request_data.type` tells what it is:
- `SERVER_DATA_PUSH_REQUEST_TYPE_ELECTRONIC_SIGNATURE_REQUEST`: sign an operation. Needs a
response.
- `SERVER_DATA_PUSH_REQUEST_TYPE_EXTENSION_AUTHENTICATION_REQUEST`: authenticate the user to a
vault application or external repository. Needs a response.
- `SERVER_DATA_PUSH_REQUEST_TYPE_OBJECTS_CHANGED_NOTIFICATION`: object versions that the
server changed on behalf of this session; refresh any cached copies. No response.
4. Answer a request with
[SendDataPushResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/SendDataPushResponse/index.md), passing its
`response_id`. If preparing the answer takes time (the user is typing), send
[SendPushDataPendingHeartbeat](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataPendingHeartbeat/index.md) with the
same ID every few seconds.
**Timing.** While the original call waits for the answer, the server gives up, and fails the
original call, if the request is not delivered to an open channel within about 10 seconds, or
if neither an answer nor a heartbeat arrives within about 35 seconds. In the latter case the
server also closes the push channel; open it again. When the waiting call holds a database
transaction, the server waits at most about 20 seconds and then fails the call with an error
that asks the client to retry it. These are server defaults that administrators can change.
**Open the channel early.** Operations that need a response from the client fail if the session
has never opened a push channel. Requests that arrive while no stream is open are queued and
delivered when the next stream opens.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md) | Opens the session's push channel: a stream of requests and notifications from the server. | `write` `session` `server streaming` |
| [SendDataPushResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/SendDataPushResponse/index.md) | Sends the client's answer to a push request received from [OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md). | `write` `session` |
---
# IRPCServerDataPush.OpenServerDataPush
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Server push](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/
Badges: `Vault API / standard` `write` `session` `server streaming`
Opens the session's push channel: a stream of requests and notifications from the server.
- **Service:** [Server push](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/index.md) `MFiles.IRPCServerDataPush`
- **gRPC method:** `/MFiles.IRPCServerDataPush/OpenServerDataPush`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/open-server-data-push`
- **Request:** [`OpenServerDataPushRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md#request)
- **Response:** [`ServerDataPushItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** server
## Remarks
- Requires a vault session in `mfiles-session-id-bin`; without one the call fails with
`UNAUTHENTICATED`. No special vault rights are needed.
- The stream has no deadline on the server side and sends nothing while there is nothing to
push. It ends with status `OK` when another stream is opened for the same session or when
the session logs out.
- Requests queued while no stream was open are sent first. A queued request whose waiting call
has already given up arrives with `response_id` 0.
- See the service overview for the message types and the timing rules.
## Request: OpenServerDataPushRequest
Request to open the server data push channel.
No fields.
## Response: ServerDataPushItem
One push message from the server: a request or a notification for the client.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `activity_id` | `string` | The activity ID of the client call that caused the request, as a GUID string in braces. Use it to tie the request to the call that is waiting for it. A GUID of zeros for notifications that no call is waiting for. |
| `response_id` | `int32` | The ID to send back in [SendDataPushResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/SendDataPushResponse/index.md). Respond only to request types that need a response, and never when the ID is 0. |
| `request_data` | [`ServerDataPushRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerDataPushRequest/index.md) | What the server asks for or tells. See [ServerDataPushRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerDataPushRequest/index.md). |
| `request_data.type` | [`ServerDataPushRequestType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerDataPushRequestType/index.md) | Request type. Values: `SERVER_DATA_PUSH_REQUEST_TYPE_UNINITIALIZED` (0), `SERVER_DATA_PUSH_REQUEST_TYPE_ELECTRONIC_SIGNATURE_REQUEST` (1), `SERVER_DATA_PUSH_REQUEST_TYPE_EXTENSION_AUTHENTICATION_REQUEST` (2), `SERVER_DATA_PUSH_REQUEST_TYPE_OBJECTS_CHANGED_NOTIFICATION` (3). |
| `request_data.data` | [`ServerDataPushRequestUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerDataPushRequestUnion/index.md) | The actual message data. |
| `request_data.data.electronic_signature_request` | [`ElectronicSignatureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureRequest/index.md) (oneof data) | Electronic signature request. |
| `request_data.data.extension_authentication_request` | [`ExtensionAuthenticationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtensionAuthenticationRequest/index.md) (oneof data) | Extension authentication request. |
| `request_data.data.objects_changed_notification` | [`ObjectsChangedNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectsChangedNotification/index.md) (oneof data) | Objects changed notification. |
---
# IRPCServerDataPush.SendDataPushResponse
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Server push](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/SendDataPushResponse/
Badges: `Vault API / standard` `write` `session`
Sends the client's answer to a push request received from
[OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md).
- **Service:** [Server push](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/index.md) `MFiles.IRPCServerDataPush`
- **gRPC method:** `/MFiles.IRPCServerDataPush/SendDataPushResponse`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/send-data-push-response`
- **Request:** [`SendDataPushResponseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/SendDataPushResponse/index.md#request)
- **Response:** [`SendDataPushResponseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/SendDataPushResponse/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the same vault session that received the request.
- `id` must be the `response_id` of a request that the server is still waiting for. Any other
ID, including 0, an ID of a notification, or an ID whose wait has timed out, fails with "The
parameter is incorrect. ()".
- Has the same effect as [SendPushDataResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md).
## Request: SendDataPushResponseRequest
The request of SendDataPushResponse: the client's answer to a push 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 |
|---|---|---|
| `id` | `int32` | The `response_id` of the [ServerDataPushItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md#response) being answered. |
| `response_data` | [`ServerDataPushResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerDataPushResponse/index.md) | The answer: set `type` to the type of the request and fill the matching member of `data`, or report a failure in `error`. See [ServerDataPushResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerDataPushResponse/index.md). |
| `response_data.type` | [`ServerDataPushRequestType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerDataPushRequestType/index.md) | Response type. Values: `SERVER_DATA_PUSH_REQUEST_TYPE_UNINITIALIZED` (0), `SERVER_DATA_PUSH_REQUEST_TYPE_ELECTRONIC_SIGNATURE_REQUEST` (1), `SERVER_DATA_PUSH_REQUEST_TYPE_EXTENSION_AUTHENTICATION_REQUEST` (2), `SERVER_DATA_PUSH_REQUEST_TYPE_OBJECTS_CHANGED_NOTIFICATION` (3). |
| `response_data.data` | [`ServerDataPushResponseUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerDataPushResponseUnion/index.md) | The actual message data. |
| `response_data.data.electronic_signature_request` | [`ElectronicSignatureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureResponse/index.md) (oneof data) | Electronic signature response. |
| `response_data.data.extension_authentication_request` | [`ExtensionAuthenticationResponseFromClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtensionAuthenticationResponseFromClient/index.md) (oneof data) | Extension authentication response. Encrypted with the server public key. |
| `response_data.error` | [`RPCErrorInfoArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RPCErrorInfoArray/index.md) | Possible error encountered when serving the request. |
| `response_data.error.value[]` | repeated [`RPCErrorInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RPCErrorInfo/index.md) | Array of errors. |
## Response: SendDataPushResponseResponse
Response for the SendDataPushResponse call.
No fields.
## Related methods
- [OpenServerDataPush](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerDataPush/OpenServerDataPush/index.md): Opens the session's push channel: a stream of requests and notifications from the server.
- [IRPCVault.SendPushDataResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/SendPushDataResponse/index.md): Sends a response for server data push. This is a response for request received with RequestPushDataAsync call (with non-zero request id). This call completes the push data cycle.
---
# Notification rules (IRPCNotificationRules)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/
Manages notification rules: which events on which objects send the user a notification.
- **gRPC service:** `MFiles.IRPCNotificationRules`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCNotificationRules.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCNotificationRules.proto)
## Overview
A notification rule ([NotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NotificationRule/index.md)) combines a filter
(`object_filter`, search conditions), the events to watch (`subscriptions`, such as
`EVENT_TYPE_OBJECT_CREATED` or `EVENT_TYPE_OBJECT_CHANGED`) and delivery options (`options`).
Notifications are sent by e-mail, and only when notifications are enabled on the server and in
the vault and the user has not turned them off (see
[GetNotificationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/GetNotificationConfiguration/index.md)).
There are two kinds of rules:
| Kind | `is_common` | Who manages it | Who it notifies |
| --- | --- | --- | --- |
| Private | false | users with the vault right `manage_private_notification_rules` | the owner |
| Common | true | users with the vault right `manage_common_notification_rules` | the users and groups in `recipients` |
Typical use:
1. [GetNotificationRules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/index.md) to list the
rules that apply to the caller.
2. [AddNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/index.md),
[ModifyNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/ModifyNotificationRule/index.md) and
[RemoveNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/RemoveNotificationRule/index.md) to change
them. Rules are identified by `id`.
To follow a single object, use
[FollowObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/FollowObject/index.md) instead of building the rule
yourself. Rights are listed in [VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md); filters use the search
conditions described in
[Search](https://developer.m-files.com/APIs/gRPC-API/concepts/search/index.md).
**Filter-based rules.** A rule whose only subscription is `EVENT_TYPE_OBJECT_NOTIFICATION`
notifies about the objects that match its filter, for example as a reminder, instead of about
events. Only such rules use `options.recurring` and `notification_days_of_week`. The server keeps
these two fields only if the session was opened with
`ClientData.capabilities.recurring_notifications` set; otherwise it saves `recurring` as false and
`notification_days_of_week` as every day (127).
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AddNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/index.md) | Creates a notification rule and returns its ID. | `write` `session` `returns metadata structure version` |
| [GetNotificationRules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/index.md) | Gets the caller's private notification rules and the common rules that apply to the caller. | `read` `session` `idempotent` `returns metadata structure version` |
| [ModifyNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/ModifyNotificationRule/index.md) | Replaces a notification rule, identified by its `id`, with the given definition. | `write` `session` `idempotent` `returns metadata structure version` |
| [RemoveNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/RemoveNotificationRule/index.md) | Deletes a notification rule. | `write` `session` `returns metadata structure version` |
---
# IRPCNotificationRules.AddNotificationRule
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Creates a notification rule and returns its ID.
- **Service:** [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md) `MFiles.IRPCNotificationRules`
- **gRPC method:** `/MFiles.IRPCNotificationRules/AddNotificationRule`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-notification-rule`
- **Request:** [`AddNotificationRuleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/index.md#request)
- **Response:** [`AddNotificationRuleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- A private rule (`is_common` false) requires the vault right
`manage_private_notification_rules` and belongs to the caller. A common rule requires
`manage_common_notification_rules`. Otherwise the call fails with "Access denied.".
- `name` must not be empty ("The parameter is incorrect."). `id` is ignored: the server assigns
a new ID. Names need not be unique, so a retried call creates a second rule.
- `recipients` must be a plain access control list of users and groups; pseudo-users such as
"current user" are rejected.
- See the service overview for `recurring` and `notification_days_of_week`.
## Request: AddNotificationRuleRequest
> 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 |
|---|---|---|
| `utf8szrule` | [`NotificationRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NotificationRule/index.md) | The rule to create. Set `name`, `subscriptions` and usually `object_filter` and `options.is_enabled`; for a common rule also `is_common` and `recipients`. `id` is ignored. |
| `utf8szrule.id` | `int32` | The ID of the rule. Assigned by the server when the rule is created. |
| `utf8szrule.name` | `string` | The name of the notification rule. |
| `utf8szrule.object_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The search conditions that an object must meet for the rule to apply, combined with AND. The built-in rules include a "not deleted" condition (`STATUS_TYPE_IS_DELETED` equal to false). |
| `utf8szrule.object_filter[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `utf8szrule.object_filter[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `utf8szrule.object_filter[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `utf8szrule.subscriptions[]` | repeated [`EventSubscription`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventSubscription/index.md) | The events that trigger a notification. A single `EVENT_TYPE_OBJECT_NOTIFICATION` subscription makes the rule filter-based: it then notifies about the objects that match `object_filter`. |
| `utf8szrule.subscriptions[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. [ switch_is( eventtype ) ] EventTypeSpecificDataUnion etsdu; //!< Additional event type -specific data as a union. |
| `utf8szrule.options` | [`NOTIFICATIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NOTIFICATIONFLAGS/index.md) | `is_enabled` turns the rule on, `send_digest` combines the day's notifications into one message, `exclude_self_triggered` leaves out events caused by the user, and `recurring` (filter-based rules only) repeats the notification for objects that still match. |
| `utf8szrule.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `utf8szrule.options.is_enabled` | `bool` | Notifications enabled. |
| `utf8szrule.options.send_digest` | `bool` | Combine the day's notifications into a single message. |
| `utf8szrule.options.exclude_self_triggered` | `bool` | Exclude notifications of events caused by me. |
| `utf8szrule.options.recurring` | `bool` | Notifications are recurring (not only appear once per a matching object). |
| `utf8szrule.is_common` | `bool` | True for a common rule that notifies the users and groups in `recipients`; false for a private rule of its owner. |
| `utf8szrule.recipients` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | For a common rule, the users and groups to notify. Not used by private rules. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.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. |
| `utf8szrule.notification_days_of_week` | `uint32` | For filter-based rules, the days on which the rule is processed, as a bit mask: 1 Sunday, 2 Monday, 4 Tuesday, 8 Wednesday, 16 Thursday, 32 Friday, 64 Saturday. 127 means every day. |
## Response: AddNotificationRuleResponse
> Nested 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 rule. |
---
# IRPCNotificationRules.GetNotificationRules
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the caller's private notification rules and the common rules that apply to the caller.
- **Service:** [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md) `MFiles.IRPCNotificationRules`
- **gRPC method:** `/MFiles.IRPCNotificationRules/GetNotificationRules`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-notification-rules`
- **Request:** [`GetNotificationRulesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/index.md#request)
- **Response:** [`GetNotificationRulesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Common rules are returned when the caller is among their `recipients`, or when the caller has
the vault right `see_all_objects`. Private rules of other users are never returned.
- The order of the rules is not specified.
## Request: GetNotificationRulesRequest
No fields.
## Response: GetNotificationRulesResponse
> 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 |
|---|---|---|
| `rules[]` | repeated [`NotificationRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NotificationRule/index.md) | The rules. Built-in common rules, such as "Assigned to me", have small fixed IDs. |
| `rules[].id` | `int32` | The ID of the rule. Assigned by the server when the rule is created. |
| `rules[].name` | `string` | The name of the notification rule. |
| `rules[].object_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The search conditions that an object must meet for the rule to apply, combined with AND. The built-in rules include a "not deleted" condition (`STATUS_TYPE_IS_DELETED` equal to false). |
| `rules[].object_filter[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `rules[].object_filter[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `rules[].object_filter[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `rules[].subscriptions[]` | repeated [`EventSubscription`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventSubscription/index.md) | The events that trigger a notification. A single `EVENT_TYPE_OBJECT_NOTIFICATION` subscription makes the rule filter-based: it then notifies about the objects that match `object_filter`. |
| `rules[].subscriptions[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. [ switch_is( eventtype ) ] EventTypeSpecificDataUnion etsdu; //!< Additional event type -specific data as a union. |
| `rules[].options` | [`NOTIFICATIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NOTIFICATIONFLAGS/index.md) | `is_enabled` turns the rule on, `send_digest` combines the day's notifications into one message, `exclude_self_triggered` leaves out events caused by the user, and `recurring` (filter-based rules only) repeats the notification for objects that still match. |
| `rules[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `rules[].options.is_enabled` | `bool` | Notifications enabled. |
| `rules[].options.send_digest` | `bool` | Combine the day's notifications into a single message. |
| `rules[].options.exclude_self_triggered` | `bool` | Exclude notifications of events caused by me. |
| `rules[].options.recurring` | `bool` | Notifications are recurring (not only appear once per a matching object). |
| `rules[].is_common` | `bool` | True for a common rule that notifies the users and groups in `recipients`; false for a private rule of its owner. |
| `rules[].recipients` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | For a common rule, the users and groups to notify. Not used by private rules. |
| `rules[].recipients.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. |
| `rules[].recipients.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. |
| `rules[].recipients.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `rules[].recipients.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. |
| `rules[].recipients.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. |
| `rules[].recipients.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. |
| `rules[].notification_days_of_week` | `uint32` | For filter-based rules, the days on which the rule is processed, as a bit mask: 1 Sunday, 2 Monday, 4 Tuesday, 8 Wednesday, 16 Thursday, 32 Friday, 64 Saturday. 127 means every day. |
---
# IRPCNotificationRules.ModifyNotificationRule
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/ModifyNotificationRule/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Replaces a notification rule, identified by its `id`, with the given definition.
- **Service:** [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md) `MFiles.IRPCNotificationRules`
- **gRPC method:** `/MFiles.IRPCNotificationRules/ModifyNotificationRule`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-notification-rule`
- **Request:** [`ModifyNotificationRuleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/ModifyNotificationRule/index.md#request)
- **Response:** [`ModifyNotificationRuleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/ModifyNotificationRule/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Send the complete rule: read it with
[GetNotificationRules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/index.md), change it
and send it back. The subscriptions are replaced as a whole.
- Saving a private rule (`is_common` false) requires `manage_private_notification_rules`;
saving a common rule requires `manage_common_notification_rules`.
- An unknown `id` fails with "Not found.". The same validation as in
[AddNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/index.md) applies.
## Request: ModifyNotificationRuleRequest
> 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 |
|---|---|---|
| `utf8szrule` | [`NotificationRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NotificationRule/index.md) | The complete new definition of the rule. `id` identifies the rule to change. |
| `utf8szrule.id` | `int32` | The ID of the rule. Assigned by the server when the rule is created. |
| `utf8szrule.name` | `string` | The name of the notification rule. |
| `utf8szrule.object_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The search conditions that an object must meet for the rule to apply, combined with AND. The built-in rules include a "not deleted" condition (`STATUS_TYPE_IS_DELETED` equal to false). |
| `utf8szrule.object_filter[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `utf8szrule.object_filter[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `utf8szrule.object_filter[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `utf8szrule.subscriptions[]` | repeated [`EventSubscription`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventSubscription/index.md) | The events that trigger a notification. A single `EVENT_TYPE_OBJECT_NOTIFICATION` subscription makes the rule filter-based: it then notifies about the objects that match `object_filter`. |
| `utf8szrule.subscriptions[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. [ switch_is( eventtype ) ] EventTypeSpecificDataUnion etsdu; //!< Additional event type -specific data as a union. |
| `utf8szrule.options` | [`NOTIFICATIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NOTIFICATIONFLAGS/index.md) | `is_enabled` turns the rule on, `send_digest` combines the day's notifications into one message, `exclude_self_triggered` leaves out events caused by the user, and `recurring` (filter-based rules only) repeats the notification for objects that still match. |
| `utf8szrule.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `utf8szrule.options.is_enabled` | `bool` | Notifications enabled. |
| `utf8szrule.options.send_digest` | `bool` | Combine the day's notifications into a single message. |
| `utf8szrule.options.exclude_self_triggered` | `bool` | Exclude notifications of events caused by me. |
| `utf8szrule.options.recurring` | `bool` | Notifications are recurring (not only appear once per a matching object). |
| `utf8szrule.is_common` | `bool` | True for a common rule that notifies the users and groups in `recipients`; false for a private rule of its owner. |
| `utf8szrule.recipients` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | For a common rule, the users and groups to notify. Not used by private rules. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.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. |
| `utf8szrule.recipients.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. |
| `utf8szrule.notification_days_of_week` | `uint32` | For filter-based rules, the days on which the rule is processed, as a bit mask: 1 Sunday, 2 Monday, 4 Tuesday, 8 Wednesday, 16 Thursday, 32 Friday, 64 Saturday. 127 means every day. |
## Response: ModifyNotificationRuleResponse
No fields.
## Related methods
- [GetNotificationRules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/GetNotificationRules/index.md): Gets the caller's private notification rules and the common rules that apply to the caller.
- [AddNotificationRule](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/AddNotificationRule/index.md): Creates a notification rule and returns its ID.
---
# IRPCNotificationRules.RemoveNotificationRule
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/RemoveNotificationRule/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Deletes a notification rule.
- **Service:** [Notification rules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md) `MFiles.IRPCNotificationRules`
- **gRPC method:** `/MFiles.IRPCNotificationRules/RemoveNotificationRule`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-notification-rule`
- **Request:** [`RemoveNotificationRuleRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/RemoveNotificationRule/index.md#request)
- **Response:** [`RemoveNotificationRuleResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/RemoveNotificationRule/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Callers can delete their own private rules (no special right needed) and, with the vault
right `manage_common_notification_rules`, common rules.
- Any other ID, including a private rule of another user, fails with "Not found.".
## Request: RemoveNotificationRuleRequest
> Nested 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 rule to delete. |
## Response: RemoveNotificationRuleResponse
No fields.
---
# Shared links (IRPCSharedLinks)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/
Creates and manages shared links to files for people outside the vault.
- **gRPC service:** `MFiles.IRPCSharedLinks`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 15
- **Proto file:** [`mfiles/IRPCSharedLinks.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCSharedLinks.proto)
## Overview
Creates and manages shared links: links that give people outside the vault access to one file of
a document. A link is identified by its **access key**, a 64-character random string that the
server generates. Anyone who has the access key and the vault GUID can use the link through
[IRPCSharedLinksPublic](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) without logging in, so treat access
keys as secrets.
Link types ([SharedLinkType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md)):
- `SHARED_LINK_TYPE_READ_ONLY`: a public download link. Anyone with the key can download the
file. Points to a specific checked-in object version.
- `SHARED_LINK_TYPE_EXTERNAL`: an external link, shared with named visitors (recipients) that
each have an expiration time and access type, or with anyone who has the link
(`is_anyone_access_granted`). Points to the latest version.
- `SHARED_LINK_TYPE_VISITOR`: the older form of a link shared with named visitors. Points to
the latest version.
- `SHARED_LINK_TYPE_CO_AUTHORING`, `SHARED_LINK_TYPE_WOPIREADONLY`, `SHARED_LINK_TYPE_WOPIEDIT`:
internal links for co-authoring and Office for the web, used by M-Files clients.
Typical flows:
- **Public download link**:
[CreateSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/CreateSharedLink/index.md) with
`SHARED_LINK_TYPE_READ_ONLY`; list with
[GetSharedLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/index.md) or
[GetSharedLinksByObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinksByObject/index.md); remove with
[DeleteSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/DeleteSharedLink/index.md).
- **External link**: check
[GetExternalSharingSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md), create
the link with `SHARED_LINK_TYPE_EXTERNAL`, add visitors with
[AddSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/index.md), and manage
them with [GetSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinkRecipients/index.md),
[SetSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinkRecipients/index.md) and
[RemoveSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveSharedLinkRecipients/index.md). Grant
or revoke access for anyone with the link with
[SetSharedLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinks/index.md). List an object's external
links with [GetExternalLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/index.md).
Prerequisites: sharing must be enabled on the server and in the vault; otherwise the methods fail
with "Access denied." (except for the internal link types). Read-only links, and external links
open to anyone, also need the vault setting that allows sharing with anyone who has the link.
Anonymous sessions cannot use this service.
**Times.** An unset expiration time means "never expires"; the server returns it as
1601-01-01T00:00:00Z. A recipient added without an expiration time is returned with
1753-01-01T00:00:00Z.
**Errors.** An unknown, deleted or expired access key fails with "The link is either expired or
invalid.".
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AddSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/index.md) | Adds visitors (email recipients) to an external or visitor link and returns all its recipients. | `write` `session or assertion` `returns metadata structure version` |
| [CreateSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/CreateSharedLink/index.md) | Creates a shared link to one file of an object and returns it with its new access key. | `write` `session or assertion` `returns metadata structure version` |
| [DeleteSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/DeleteSharedLink/index.md) | Deletes a shared link, so that its access key stops working. | `write` `session or assertion` `returns metadata structure version` |
| [GetExternalLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/index.md) | Lists the external links of an object. | `write` `session or assertion` `returns metadata structure version` |
| [GetExternalSharingSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md) | Tells whether sharing is enabled in the vault and what the caller may do with external links. | `write` `session or assertion` `returns metadata structure version` |
| [GetSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLink/index.md) | Gets one shared link by its access key. | `write` `session or assertion` `returns metadata structure version` |
| [GetSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinkRecipients/index.md) | Lists the visitors (email recipients) of an external or visitor link. | `write` `session or assertion` `returns metadata structure version` |
| [GetSharedLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/index.md) | Lists the shared links that the caller created, or all links for users who can see all objects. | `write` `session or assertion` `returns metadata structure version` |
| [GetSharedLinksByObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinksByObject/index.md) | Lists the shared links to one object. | `write` `session or assertion` `returns metadata structure version` |
| [GetWOPILock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetWOPILock/index.md) | Not supported: always fails with "Not implemented.". | `write` `no session` |
| [RemoveSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveSharedLinkRecipients/index.md) | Removes visitors from an external or visitor link. | `write` `session or assertion` |
| [RemoveWOPILock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveWOPILock/index.md) | Not supported: always fails with "Not implemented.". | `write` `no session` |
| [SetSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinkRecipients/index.md) | Updates the expiration time and access type of visitors of external links. | `write` `session or assertion` `returns metadata structure version` |
| [SetSharedLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinks/index.md) | Updates the access type of shared links, and grants or revokes access for anyone who has the link. | `write` `session or assertion` `returns metadata structure version` |
| [SetWOPILock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetWOPILock/index.md) | Not supported: always fails with "Not implemented.". | `write` `no session` |
---
# IRPCSharedLinks.AddSharedLinkRecipients
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Adds visitors (email recipients) to an external or visitor link and returns all its recipients.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/AddSharedLinkRecipients`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-shared-link-recipients`
- **Request:** [`AddSharedLinkRecipientsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/index.md#request)
- **Response:** [`AddSharedLinkRecipientsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- The link must be an external or visitor link; other types fail with "The parameter is
incorrect.". `emails` must not be empty.
- Each entry is an email address, optionally in mailbox form (`Name `). An
invalid address fails the call with the invalid email address error (0x80040811), which has no
description text.
- Recipients that the caller has already added are skipped. This call does not email the
recipients.
- The creator of the link must still have read access to the object.
- Side effect: the expiration time of the link itself is set to 23:59 UTC on the Sunday about 12
weeks ahead. Recipients keep their own expiration times.
- The response lists all recipients that the caller can see, not just the added ones.
## Request: AddSharedLinkRecipientsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `access_key` | `string` | The access key of an external or visitor link. |
| `emails[]` | repeated `string` | The recipient addresses, optionally as `Name `. |
| `expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the added recipients. Unset for no expiration. |
| `external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | What the added recipients may do with the file. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
## Response: AddSharedLinkRecipientsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `recipients[]` | repeated [`SharedLinkRecipient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkRecipient/index.md) | All recipients of the link that the caller can see. |
| `recipients[].email` | `string` | The recipient email. |
| `recipients[].access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The access time for the shared link. Is set by the server. |
| `recipients[].created_by_user` | `int32` | The creator of this shared Link. |
| `recipients[].shared_link_notification` | [`SharedLinkNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkNotification/index.md) | Shared link notification type. Values: `SHARED_LINK_NOTIFICATION_NONE` (0), `SHARED_LINK_NOTIFICATION_ALWAYS` (1). |
| `recipients[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `recipients[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | The access type of the recipient. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `recipients[].created_by_user_name` | `string` | The user who created the shared link. |
---
# IRPCSharedLinks.CreateSharedLink
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/CreateSharedLink/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Creates a shared link to one file of an object and returns it with its new access key.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/CreateSharedLink`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-shared-link`
- **Request:** [`CreateSharedLinkRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/CreateSharedLink/index.md#request)
- **Response:** [`CreateSharedLinkResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/CreateSharedLink/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires read access to the object version. Read-only, external and visitor links can be
created by users whose license does not allow modifications; the other types need
`license_allows_modifications`. When print prevention is enabled in the vault, the user also
needs the right to download the file.
- Leave `access_key`, `created_at_utc` and `created_by_user` unset (or set `created_by_user` to
the caller's own ID); otherwise the call fails with "The parameter is incorrect.". `file_ver`
must name one file; sharing all files of an object is not supported.
- `SHARED_LINK_TYPE_READ_ONLY`: `obj_ver` must be a specific, checked-in version and
`file_ver.type` must be `FILE_VER_TYPE_ANY` (other file version types fail with "The parameter
is incorrect. (FileVersion)"). Links to the latest version fail with "Access denied." unless
the vault allows them, and links to a checked-out version fail.
- `SHARED_LINK_TYPE_EXTERNAL` and `SHARED_LINK_TYPE_VISITOR`: `obj_ver` and `file_ver` must
refer to the latest version; a specific version fails with "Access denied.". Add visitors
afterwards with [AddSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/index.md).
- The creation is recorded in the vault's event log.
## Request: CreateSharedLinkRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `sl_info` | [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The link to create: `shared_link_type`, `obj_ver`, `file_ver`, and optionally `description`, `expires_at_utc` (unset for no expiration) and, for external links, `external_shared_link_access_type` and `is_anyone_access_granted`. |
| `sl_info.access_key` | `string` | The access key of the shared link. |
| `sl_info.description` | `string` | The description of the shared link. |
| `sl_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `sl_info.expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `sl_info.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `sl_info.obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `sl_info.obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `sl_info.created_by_user` | `int32` | The creator of this shared Link. |
| `sl_info.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `sl_info.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `sl_info.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `sl_info.file_ver.internal_version` | `int32` | The file version number. |
| `sl_info.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `sl_info.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `sl_info.shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `sl_info.is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `sl_info.anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `sl_info.external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `sl_info.created_by_user_name` | `string` | The user who created the shared link. |
| `sl_info.anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
## Response: CreateSharedLinkResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `sl_info_result` | [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The created link, including its `access_key`. |
| `sl_info_result.access_key` | `string` | The access key of the shared link. |
| `sl_info_result.description` | `string` | The description of the shared link. |
| `sl_info_result.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `sl_info_result.expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `sl_info_result.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `sl_info_result.obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `sl_info_result.obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `sl_info_result.created_by_user` | `int32` | The creator of this shared Link. |
| `sl_info_result.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `sl_info_result.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `sl_info_result.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `sl_info_result.file_ver.internal_version` | `int32` | The file version number. |
| `sl_info_result.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `sl_info_result.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `sl_info_result.shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `sl_info_result.is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `sl_info_result.anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `sl_info_result.external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `sl_info_result.created_by_user_name` | `string` | The user who created the shared link. |
| `sl_info_result.anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
## Related methods
- [AddSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/AddSharedLinkRecipients/index.md): Adds visitors (email recipients) to an external or visitor link and returns all its recipients.
---
# IRPCSharedLinks.DeleteSharedLink
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/DeleteSharedLink/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Deletes a shared link, so that its access key stops working.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/DeleteSharedLink`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/delete-shared-link`
- **Request:** [`DeleteSharedLinkRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/DeleteSharedLink/index.md#request)
- **Response:** [`DeleteSharedLinkResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/DeleteSharedLink/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Read-only and other non-visitor links: the creator, or a user with the vault right
`see_all_objects`, can delete them; others get "Access denied.".
- External links: any user who can see the full list of visitors (see
`visitor_list_restricted` in
[GetExternalSharingSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md)) can
delete the link, including links that other users created. The link and its recipients are
removed.
- Visitor links: only the recipients are removed; the link itself remains.
- An unknown or already deleted key fails with "The link is either expired or invalid.".
## Request: DeleteSharedLinkRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `access_key` | `string` | The access key of the link. |
## Response: DeleteSharedLinkResponse
No fields.
## Related methods
- [GetExternalSharingSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md): Tells whether sharing is enabled in the vault and what the caller may do with external links.
---
# IRPCSharedLinks.GetExternalLinks
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Lists the external links of an object.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetExternalLinks`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-links`
- **Request:** [`GetExternalLinksRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/index.md#request)
- **Response:** [`GetExternalLinksResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Users with the vault right `see_all_objects`, and users with access to the latest version of
the object, get all external links of the object; other users get the links they created.
## Request: GetExternalLinksRequest
> Nested 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 object. |
| `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. |
## Response: GetExternalLinksResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `external_shared_links[]` | repeated [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The external links, including their access keys. |
| `external_shared_links[].access_key` | `string` | The access key of the shared link. |
| `external_shared_links[].description` | `string` | The description of the shared link. |
| `external_shared_links[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `external_shared_links[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `external_shared_links[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `external_shared_links[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `external_shared_links[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `external_shared_links[].created_by_user` | `int32` | The creator of this shared Link. |
| `external_shared_links[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `external_shared_links[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `external_shared_links[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `external_shared_links[].file_ver.internal_version` | `int32` | The file version number. |
| `external_shared_links[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `external_shared_links[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `external_shared_links[].shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `external_shared_links[].is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `external_shared_links[].anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `external_shared_links[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `external_shared_links[].created_by_user_name` | `string` | The user who created the shared link. |
| `external_shared_links[].anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
| `legacy_shared_link_exist` | `bool` | True if the latest version of the object also has read-only or visitor links. |
---
# IRPCSharedLinks.GetExternalSharingSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Tells whether sharing is enabled in the vault and what the caller may do with external links.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetExternalSharingSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-sharing-settings`
- **Request:** [`GetExternalSharingSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md#request)
- **Response:** [`GetExternalSharingSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. Does not fail when sharing is disabled; check `sharing_enabled`.
## Request: GetExternalSharingSettingsRequest
No fields.
## Response: GetExternalSharingSettingsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `allow_sharing_to_anyone_with_the_link` | `bool` | True if links may be opened by anyone who has them (read-only links and external links with anyone access). |
| `sharing_enabled` | `bool` | True if sharing is enabled on the server and in the vault. |
| `visitor_list_restricted` | `bool` | True if the caller sees only the visitors they added, not all visitors of a link. |
---
# IRPCSharedLinks.GetSharedLink
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLink/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Gets one shared link by its access key.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetSharedLink`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-shared-link`
- **Request:** [`GetSharedLinkRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLink/index.md#request)
- **Response:** [`GetSharedLinkResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLink/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Only the creator of the link, or a user with the vault right `see_all_objects`, can read it,
and the caller must be able to read the linked object version.
- An unknown, deleted or expired key fails with "The link is either expired or invalid.".
## Request: GetSharedLinkRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `access_key` | `string` | The access key of the link. |
## Response: GetSharedLinkResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `sl_info_result` | [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The link. |
| `sl_info_result.access_key` | `string` | The access key of the shared link. |
| `sl_info_result.description` | `string` | The description of the shared link. |
| `sl_info_result.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `sl_info_result.expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `sl_info_result.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `sl_info_result.obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `sl_info_result.obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `sl_info_result.created_by_user` | `int32` | The creator of this shared Link. |
| `sl_info_result.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `sl_info_result.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `sl_info_result.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `sl_info_result.file_ver.internal_version` | `int32` | The file version number. |
| `sl_info_result.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `sl_info_result.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `sl_info_result.shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `sl_info_result.is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `sl_info_result.anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `sl_info_result.external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `sl_info_result.created_by_user_name` | `string` | The user who created the shared link. |
| `sl_info_result.anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
## Related methods
- [GetSharedLinkRecipients](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinkRecipients/index.md): Lists the visitors (email recipients) of an external or visitor link.
---
# IRPCSharedLinks.GetSharedLinkRecipients
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinkRecipients/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Lists the visitors (email recipients) of an external or visitor link.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetSharedLinkRecipients`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-shared-link-recipients`
- **Request:** [`GetSharedLinkRecipientsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinkRecipients/index.md#request)
- **Response:** [`GetSharedLinkRecipientsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinkRecipients/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Users who cannot see the full list of visitors (see `visitor_list_restricted` in
[GetExternalSharingSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md)) get
only the recipients they added themselves.
- Recipients with a name are returned in mailbox form (`Name `).
- Reading the visitors of an external link is recorded in the vault's event log.
## Request: GetSharedLinkRecipientsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `access_key` | `string` | The access key of the link. |
## Response: GetSharedLinkRecipientsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `recipients[]` | repeated [`SharedLinkRecipient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkRecipient/index.md) | The recipients, with their expiration time and access type. |
| `recipients[].email` | `string` | The recipient email. |
| `recipients[].access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The access time for the shared link. Is set by the server. |
| `recipients[].created_by_user` | `int32` | The creator of this shared Link. |
| `recipients[].shared_link_notification` | [`SharedLinkNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkNotification/index.md) | Shared link notification type. Values: `SHARED_LINK_NOTIFICATION_NONE` (0), `SHARED_LINK_NOTIFICATION_ALWAYS` (1). |
| `recipients[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `recipients[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | The access type of the recipient. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `recipients[].created_by_user_name` | `string` | The user who created the shared link. |
## Related methods
- [GetExternalSharingSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalSharingSettings/index.md): Tells whether sharing is enabled in the vault and what the caller may do with external links.
- [GetSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLink/index.md): Gets one shared link by its access key.
---
# IRPCSharedLinks.GetSharedLinks
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Lists the shared links that the caller created, or all links for users who can see all objects.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetSharedLinks`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-shared-links`
- **Request:** [`GetSharedLinksRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/index.md#request)
- **Response:** [`GetSharedLinksResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- `by_user` must be -1 or the caller's own user ID. Any other value, including the default 0,
fails with "The parameter is incorrect. (CreatedByUser)".
- Users with the vault right `see_all_objects` get the links of all users; other users get
their own links. Links to objects that the caller cannot see are left out.
- Visitor and external links are included only when the server supports visitor links; then a
link appears once per sharing user, with `description` replaced by the comma-separated
recipients. Otherwise list external links with
[GetExternalLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/index.md).
## Request: GetSharedLinksRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `by_user` | `int32` | Set -1. The caller's own user ID gives the same result for normal users. |
## Response: GetSharedLinksResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `shared_links[]` | repeated [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The links, including their access keys. |
| `shared_links[].access_key` | `string` | The access key of the shared link. |
| `shared_links[].description` | `string` | The description of the shared link. |
| `shared_links[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `shared_links[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `shared_links[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `shared_links[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `shared_links[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `shared_links[].created_by_user` | `int32` | The creator of this shared Link. |
| `shared_links[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `shared_links[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `shared_links[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `shared_links[].file_ver.internal_version` | `int32` | The file version number. |
| `shared_links[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `shared_links[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `shared_links[].shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `shared_links[].is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `shared_links[].anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `shared_links[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `shared_links[].created_by_user_name` | `string` | The user who created the shared link. |
| `shared_links[].anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
## Related methods
- [GetExternalLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetExternalLinks/index.md): Lists the external links of an object.
- [GetSharedLinksByObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinksByObject/index.md): Lists the shared links to one object.
---
# IRPCSharedLinks.GetSharedLinksByObject
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinksByObject/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Lists the shared links to one object.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetSharedLinksByObject`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-shared-links-by-object`
- **Request:** [`GetSharedLinksByObjectRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinksByObject/index.md#request)
- **Response:** [`GetSharedLinksByObjectResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinksByObject/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Same rules as [GetSharedLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/index.md): users with the
vault right `see_all_objects` get every user's links, other users only their own.
## Request: GetSharedLinksByObjectRequest
> Nested 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 object. |
| `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. |
## Response: GetSharedLinksByObjectResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `shared_links[]` | repeated [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The links to the object. |
| `shared_links[].access_key` | `string` | The access key of the shared link. |
| `shared_links[].description` | `string` | The description of the shared link. |
| `shared_links[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `shared_links[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `shared_links[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `shared_links[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `shared_links[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `shared_links[].created_by_user` | `int32` | The creator of this shared Link. |
| `shared_links[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `shared_links[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `shared_links[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `shared_links[].file_ver.internal_version` | `int32` | The file version number. |
| `shared_links[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `shared_links[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `shared_links[].shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `shared_links[].is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `shared_links[].anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `shared_links[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `shared_links[].created_by_user_name` | `string` | The user who created the shared link. |
| `shared_links[].anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
## Related methods
- [GetSharedLinks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetSharedLinks/index.md): Lists the shared links that the caller created, or all links for users who can see all objects.
---
# IRPCSharedLinks.GetWOPILock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetWOPILock/
Badges: `Vault API / standard` `write` `no session`
Not supported: always fails with "Not implemented.".
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/GetWOPILock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-wopilock`
- **Request:** [`GetWOPILockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetWOPILock/index.md#request)
- **Response:** [`GetWOPILockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/GetWOPILock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetWOPILockRequest
> Nested 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 vault identifier. |
| `access_key` | `string` | Specifies the access key. |
## Response: GetWOPILockResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `info` | [`WOPILock`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WOPILock/index.md) | WOPI lock data. |
| `info.lock` | `string` | The WOPI lock key. |
---
# IRPCSharedLinks.RemoveSharedLinkRecipients
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveSharedLinkRecipients/
Badges: `Vault API / standard` `write` `session or assertion`
Removes visitors from an external or visitor link.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/RemoveSharedLinkRecipients`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-shared-link-recipients`
- **Request:** [`RemoveSharedLinkRecipientsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveSharedLinkRecipients/index.md#request)
- **Response:** [`RemoveSharedLinkRecipientsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveSharedLinkRecipients/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Give the plain email addresses (without a name). Addresses that are not recipients are
ignored.
- Users who cannot see the full list of visitors can remove only the recipients they added.
## Request: RemoveSharedLinkRecipientsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `access_key` | `string` | The access key of the link. |
| `recipients[]` | repeated `string` | The email addresses to remove. |
## Response: RemoveSharedLinkRecipientsResponse
No fields.
---
# IRPCSharedLinks.RemoveWOPILock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveWOPILock/
Badges: `Vault API / standard` `write` `no session`
Not supported: always fails with "Not implemented.".
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/RemoveWOPILock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-wopilock`
- **Request:** [`RemoveWOPILockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveWOPILock/index.md#request)
- **Response:** [`RemoveWOPILockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/RemoveWOPILock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: RemoveWOPILockRequest
> Nested 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 vault identifier. |
| `access_key` | `string` | Specifies the access key. |
## Response: RemoveWOPILockResponse
No fields.
---
# IRPCSharedLinks.SetSharedLinkRecipients
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinkRecipients/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Updates the expiration time and access type of visitors of external links.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/SetSharedLinkRecipients`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-shared-link-recipients`
- **Request:** [`SetSharedLinkRecipientsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinkRecipients/index.md#request)
- **Response:** [`SetSharedLinkRecipientsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinkRecipients/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Each entry names a link (`access_key`) and a recipient (`recipient.email`, the plain
address). `recipient.expires_at_utc` must be in the future; otherwise the call fails with
"The parameter is incorrect.".
- Users who cannot see the full list of visitors can update only the recipients they added;
other entries are left unchanged.
## Request: SetSharedLinkRecipientsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `recipients[]` | repeated [`SetSharedLinkRecipient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetSharedLinkRecipient/index.md) | The recipients to update, each with the link's `access_key` and the new `expires_at_utc` and `external_shared_link_access_type`. |
| `recipients[].access_key` | `string` | The access key of the shared link. |
| `recipients[].recipient` | [`SharedLinkRecipient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkRecipient/index.md) | The information about the shared link recipient linked to the access key to update expiration time and access type. |
| `recipients[].recipient.email` | `string` | The recipient email. |
| `recipients[].recipient.access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The access time for the shared link. Is set by the server. |
| `recipients[].recipient.created_by_user` | `int32` | The creator of this shared Link. |
| `recipients[].recipient.shared_link_notification` | [`SharedLinkNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkNotification/index.md) | Shared link notification type. Values: `SHARED_LINK_NOTIFICATION_NONE` (0), `SHARED_LINK_NOTIFICATION_ALWAYS` (1). |
| `recipients[].recipient.expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `recipients[].recipient.external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | The access type of the recipient. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `recipients[].recipient.created_by_user_name` | `string` | The user who created the shared link. |
## Response: SetSharedLinkRecipientsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `recipients[]` | repeated [`SetSharedLinkRecipient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetSharedLinkRecipient/index.md) | The updated recipients. |
| `recipients[].access_key` | `string` | The access key of the shared link. |
| `recipients[].recipient` | [`SharedLinkRecipient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkRecipient/index.md) | The information about the shared link recipient linked to the access key to update expiration time and access type. |
| `recipients[].recipient.email` | `string` | The recipient email. |
| `recipients[].recipient.access_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The access time for the shared link. Is set by the server. |
| `recipients[].recipient.created_by_user` | `int32` | The creator of this shared Link. |
| `recipients[].recipient.shared_link_notification` | [`SharedLinkNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkNotification/index.md) | Shared link notification type. Values: `SHARED_LINK_NOTIFICATION_NONE` (0), `SHARED_LINK_NOTIFICATION_ALWAYS` (1). |
| `recipients[].recipient.expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `recipients[].recipient.external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | The access type of the recipient. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `recipients[].recipient.created_by_user_name` | `string` | The user who created the shared link. |
---
# IRPCSharedLinks.SetSharedLinks
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinks/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Updates the access type of shared links, and grants or revokes access for anyone who has the
link.
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/SetSharedLinks`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-shared-links`
- **Request:** [`SetSharedLinksRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinks/index.md#request)
- **Response:** [`SetSharedLinksResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetSharedLinks/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- For each link, the server sets `external_shared_link_access_type` and the anyone-with-the-link
state from the request. Every call writes both: a link sent without
`is_anyone_access_granted` loses its anyone access.
- With `is_anyone_access_granted` true, `expires_at_utc` must be in the future (otherwise "The
parameter is incorrect.") and becomes the link's expiration time; the vault must allow sharing
with anyone who has the link. Without it, `expires_at_utc` is ignored; visitors have their own
expiration times.
- Other fields of the links are ignored. Duplicate access keys are processed once.
- The response contains the updated links. The caller must be able to read the linked objects.
## Request: SetSharedLinksRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `shared_links[]` | repeated [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The links to update, identified by `access_key`, with the new `external_shared_link_access_type`, `is_anyone_access_granted` and `expires_at_utc`. |
| `shared_links[].access_key` | `string` | The access key of the shared link. |
| `shared_links[].description` | `string` | The description of the shared link. |
| `shared_links[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `shared_links[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `shared_links[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `shared_links[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `shared_links[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `shared_links[].created_by_user` | `int32` | The creator of this shared Link. |
| `shared_links[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `shared_links[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `shared_links[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `shared_links[].file_ver.internal_version` | `int32` | The file version number. |
| `shared_links[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `shared_links[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `shared_links[].shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `shared_links[].is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `shared_links[].anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `shared_links[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `shared_links[].created_by_user_name` | `string` | The user who created the shared link. |
| `shared_links[].anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
## Response: SetSharedLinksResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `shared_links[]` | repeated [`SharedLinkInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedLinkInfo/index.md) | The links after the update. |
| `shared_links[].access_key` | `string` | The access key of the shared link. |
| `shared_links[].description` | `string` | The description of the shared link. |
| `shared_links[].created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link. |
| `shared_links[].expires_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time. |
| `shared_links[].obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `shared_links[].obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `shared_links[].obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `shared_links[].created_by_user` | `int32` | The creator of this shared Link. |
| `shared_links[].file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `shared_links[].file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `shared_links[].file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `shared_links[].file_ver.internal_version` | `int32` | The file version number. |
| `shared_links[].file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `shared_links[].file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `shared_links[].shared_link_type` | [`SharedLinkType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SharedLinkType/index.md) | Type of the shared link. Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5). |
| `shared_links[].is_anyone_access_granted` | `bool` | True if any user has granted public access to the document. |
| `shared_links[].anyone_access_granted_by_user` | `int32` | The user who has granted public access to the document. |
| `shared_links[].external_shared_link_access_type` | [`ExternalSharedLinkAccessType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalSharedLinkAccessType/index.md) | Access type of the external shared link. Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3). |
| `shared_links[].created_by_user_name` | `string` | The user who created the shared link. |
| `shared_links[].anyone_access_granted_by_user_name` | `string` | The user who granted public access. |
---
# IRPCSharedLinks.SetWOPILock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetWOPILock/
Badges: `Vault API / standard` `write` `no session`
Not supported: always fails with "Not implemented.".
- **Service:** [Shared links](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/index.md) `MFiles.IRPCSharedLinks`
- **gRPC method:** `/MFiles.IRPCSharedLinks/SetWOPILock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-wopilock`
- **Request:** [`SetWOPILockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetWOPILock/index.md#request)
- **Response:** [`SetWOPILockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/SetWOPILock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: SetWOPILockRequest
> Nested 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 vault identifier. |
| `access_key` | `string` | Specifies the access key. |
| `lock` | `string` | Specifies the WOPI lock key. |
## Response: SetWOPILockResponse
No fields.
---
# Shared links (anonymous access) (IRPCSharedLinksPublic)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/
Opens and downloads files through shared links, without logging in.
- **gRPC service:** `MFiles.IRPCSharedLinksPublic`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 7
- **Proto file:** [`mfiles/IRPCSharedLinksPublic.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCSharedLinksPublic.proto)
## Overview
The anonymous side of shared links: opens and downloads a file shared with
[CreateSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinks/CreateSharedLink/index.md). No login and no session
are needed; every call names the vault by its GUID and the link by its access key. Use it to
build a download page for people outside the vault.
**Public read-only link** (`SHARED_LINK_TYPE_READ_ONLY`, or an external link open to anyone):
1. [GetSharedLinkInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md) for the file name,
extension and size.
2. [DownloadSharedFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md)
for a download ID, the size and the MD5 checksum.
3. [DownloadSharedFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md)
in a loop until all bytes are read.
**Link shared with named visitors** (visitor links, and external links that are not open to
anyone): the visitor proves their email address first.
1. [AccessSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/AccessSharedLink/index.md) with the visitor's
email address returns an access session value. If the address is a recipient of the link,
the server emails an access code to it.
2. Pass the address, the access code and the access session in `additional_data` of
[GetSharedLinkInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md) and
[DownloadSharedFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md), as
[NamedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) entries named `RECIPIENT_EMAIL`,
`RECIPIENT_ACCESSCODE` and `ACCESS_SESSION`. Without them, an external link that is not open
to anyone fails with "Authentication required to access the shared link.".
Shared links must be enabled on the server and in the vault. An unknown, deleted or expired
access key fails with "The link is either expired or invalid.". The upload and WOPI methods
serve co-authoring and Office for the web in M-Files clients; applications rarely call them.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AccessSharedLink](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/AccessSharedLink/index.md) | Starts a visitor's access to a link shared with named visitors: returns an access session value and, if the email address is a recipient of the link, emails an access code to it. | `write` `no session` |
| [DownloadSharedFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md) | Starts downloading the file of a shared link, without logging in, and returns a download ID, the file size and its MD5 checksum. | `write` `no session` |
| [DownloadSharedFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md) | Reads one block of a file download started with DownloadSharedFile_Begin. | `write` `no session` |
| [GetSharedLinkInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md) | Gets the name, extension and size of the file that a shared link points to, without logging in. | `write` `no session` |
| [GetWOPIFileInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetWOPIFileInfo/index.md) | Gets information about the file of a link for Office for the web (WOPI) operations. Used by M-Files clients; applications rarely call it. | `write` `no session` |
| [UploadSharedFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFile/index.md) | Uploads a block of new content for a file opened for editing in Office for the web. Used by M-Files clients; applications rarely call it. | `write` `no session` |
| [UploadSharedFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit/index.md) | Completes an upload made with UploadSharedFile and stores the content in the checked-out file. Used by M-Files clients; applications rarely call it. | `write` `no session` |
---
# IRPCSharedLinksPublic.AccessSharedLink
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/AccessSharedLink/
Badges: `Vault API / standard` `write` `no session`
Starts a visitor's access to a link shared with named visitors: returns an access session value
and, if the email address is a recipient of the link, emails an access code to it.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/AccessSharedLink`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/access-shared-link`
- **Request:** [`AccessSharedLinkRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/AccessSharedLink/index.md#request)
- **Response:** [`AccessSharedLinkResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/AccessSharedLink/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- No session is needed. An email address that is not valid fails the call.
- The server returns an access session value whether or not the address is a recipient, so the
response does not reveal who the recipients are.
- Pass the access session, the email address and the access code that the visitor received to
[GetSharedLinkInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md) and
[DownloadSharedFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md) in
`additional_data` (`ACCESS_SESSION`, `RECIPIENT_EMAIL`, `RECIPIENT_ACCESSCODE`).
## Request: AccessSharedLinkRequest
Requests shared link access.
> Nested 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_vault` | `string` | The vault GUID. |
| `access_key` | `string` | The access key of the link. |
| `email` | `string` | The visitor's email address. |
## Response: AccessSharedLinkResponse
Response for shared link access 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 |
|---|---|---|
| `access_session` | `string` | The access session value to pass as `ACCESS_SESSION`. |
## Related methods
- [GetSharedLinkInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md): Gets the name, extension and size of the file that a shared link points to, without logging in.
- [DownloadSharedFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md): Starts downloading the file of a shared link, without logging in, and returns a download ID, the file size and its MD5 checksum.
---
# IRPCSharedLinksPublic.DownloadSharedFile_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/
Badges: `Vault API / standard` `write` `no session`
Starts downloading the file of a shared link, without logging in, and returns a download ID,
the file size and its MD5 checksum.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-shared-file_-begin`
- **Request:** [`DownloadSharedFile_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md#request)
- **Response:** [`DownloadSharedFile_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- No session is needed. For links shared with named visitors, pass the visitor values in
`additional_data` (see the service overview).
- Then read the content with
[DownloadSharedFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md),
sending the same `vault` and `access_key`.
- The MD5 checksum is split in two: the 16 checksum bytes are the 8 bytes of `low_digest`
followed by the 8 bytes of `high_digest`, each in little-endian order.
- Co-authoring links cannot be downloaded ("The parameter is incorrect.").
## Request: DownloadSharedFile_BeginRequest
> Nested 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 vault GUID. |
| `access_key` | `string` | The access key of the shared link. |
| `additional_data[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Optional named values; see [GetSharedLinkInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md). |
| `additional_data[].key` | `string` | The name of the value. |
| `additional_data[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `additional_data[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `additional_data[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `additional_data[].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. |
## Response: DownloadSharedFile_BeginResponse
> Nested 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 for [DownloadSharedFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md). |
| `file_size` | `int64` | The size of the file in bytes. |
| `low_digest` | `int64` | The first 8 bytes of the MD5 checksum, as a little-endian integer. |
| `high_digest` | `int64` | The last 8 bytes of the MD5 checksum, as a little-endian integer. |
## Related methods
- [DownloadSharedFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md): Reads one block of a file download started with DownloadSharedFile_Begin.
---
# IRPCSharedLinksPublic.DownloadSharedFile_ReadBlock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/
Badges: `Vault API / standard` `write` `no session`
Reads one block of a file download started with DownloadSharedFile_Begin.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-shared-file_-read-block`
- **Request:** [`DownloadSharedFile_ReadBlockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md#request)
- **Response:** [`DownloadSharedFile_ReadBlockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_ReadBlock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- No session is needed. `access_key` must be the key that started the download; another key
fails with "The link is either expired or invalid.".
- `block_size` can be at most 4 MiB (4 194 304 bytes). Read until you have `file_size` bytes; a
block can be shorter than requested. See
[Files](https://developer.m-files.com/APIs/gRPC-API/runtime/files/index.md) for block sizes and
message size limits.
## Request: DownloadSharedFile_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 |
|---|---|---|
| `vault` | `string` | The vault GUID. |
| `access_key` | `string` | The access key that started the download. |
| `download_id` | `int32` | The `download_id` from DownloadSharedFile_Begin. |
| `block_size` | `uint32` | The number of bytes to read, at most 4 194 304. |
| `offset` | `int64` | The position in the file to read from. |
## Response: DownloadSharedFile_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. |
## Related methods
- [DownloadSharedFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/DownloadSharedFile_Begin/index.md): Starts downloading the file of a shared link, without logging in, and returns a download ID, the file size and its MD5 checksum.
---
# IRPCSharedLinksPublic.GetSharedLinkInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/
Badges: `Vault API / standard` `write` `no session`
Gets the name, extension and size of the file that a shared link points to, without logging in.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-shared-link-info`
- **Request:** [`GetSharedLinkInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md#request)
- **Response:** [`GetSharedLinkInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetSharedLinkInfo/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- No session is needed. Set `vault` to the vault GUID and `access_key` to the
link's key.
- External and visitor links always point to the latest version of the file; read-only links
to the version they were created for.
- For links shared with named visitors, pass the visitor values in `additional_data` (see the
service overview).
- For read-only links, the access is recorded in the vault's event log. Add a `CLIENT_IP` entry
to `additional_data` to include the visitor's IP address in the event.
## Request: GetSharedLinkInfoRequest
> Nested 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 vault GUID, for example `{7BBEA0BC-40D8-4BCB-A67D-8A3ACFBDB575}`. |
| `access_key` | `string` | The access key of the shared link. |
| `additional_data[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Optional named values: `RECIPIENT_EMAIL`, `RECIPIENT_ACCESSCODE` and `ACCESS_SESSION` for links shared with named visitors, and `CLIENT_IP` for the event log. |
| `additional_data[].key` | `string` | The name of the value. |
| `additional_data[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `additional_data[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `additional_data[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `additional_data[].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. |
## Response: GetSharedLinkInfoResponse
> Nested 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` | [`SharedFileInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SharedFileInfo/index.md) | The file's title, extension, size and change time. |
| `result.title` | `string` | The title of the file. |
| `result.extension` | `string` | File extension, not including the dot (e.g. "doc"). |
| `result.logical_size` | `int64` | The logical size of the file in bytes. |
| `result.change_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
---
# IRPCSharedLinksPublic.GetWOPIFileInfo
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetWOPIFileInfo/
Badges: `Vault API / standard` `write` `no session`
Gets information about the file of a link for Office for the web (WOPI) operations. Used by
M-Files clients; applications rarely call it.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/GetWOPIFileInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-wopifile-info`
- **Request:** [`GetWOPIFileInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetWOPIFileInfo/index.md#request)
- **Response:** [`GetWOPIFileInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/GetWOPIFileInfo/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Request: GetWOPIFileInfoRequest
> Nested 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 vault GUID. |
| `access_key` | `string` | The access key of the link. |
## Response: GetWOPIFileInfoResponse
> Nested 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` | [`WOPIFileInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WOPIFileInfo/index.md) | The file's title, extension, size, the account name of the link's creator, and the object and file version. |
| `result.title` | `string` | The title of the file. |
| `result.extension` | `string` | File extension, not including the dot (e.g. "doc"). |
| `result.created_by_user` | `string` | The creator of this shared Link. |
| `result.logical_size` | `int64` | The logical size of the file in bytes. |
| `result.change_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `result.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version referenced by the shared link. |
| `result.obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `result.obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `result.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file version referenced by the shared link. |
| `result.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `result.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `result.file_ver.internal_version` | `int32` | The file version number. |
| `result.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `result.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
---
# IRPCSharedLinksPublic.UploadSharedFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFile/
Badges: `Vault API / standard` `write` `no session`
Uploads a block of new content for a file opened for editing in Office for the web. Used by
M-Files clients; applications rarely call it.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/UploadSharedFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-shared-file`
- **Request:** [`UploadSharedFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFile/index.md#request)
- **Response:** [`UploadSharedFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFile/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Works only with links of type `SHARED_LINK_TYPE_WOPIEDIT`; other links fail with "The
parameter is incorrect.".
- Start with `upload_id` 0 and `offset` 0, then send the following blocks with the returned
`upload_id`. Finish with
[UploadSharedFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit/index.md).
## Request: UploadSharedFileRequest
> Nested 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_vault` | `string` | The vault GUID. |
| `access_key` | `string` | The access key of the editing link. |
| `upload_id` | `int32` | 0 for the first block; then the `upload_id` that the first call returned. |
| `additional_data[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Optional named values. Can be empty. |
| `additional_data[].key` | `string` | The name of the value. |
| `additional_data[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `additional_data[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `additional_data[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `additional_data[].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. |
| `total_size_in_bytes` | `int64` | The total size of the file. Read only with the first block (`offset` 0). |
| `offset` | `int64` | The position of this block in the file. Use multiples of 4096 bytes. |
| `data` | `bytes` | The bytes of this block. |
## Response: UploadSharedFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | The upload ID to use for the following blocks and the commit. |
## Related methods
- [UploadSharedFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit/index.md): Completes an upload made with UploadSharedFile and stores the content in the checked-out file. Used by M-Files clients; applications rarely call it.
---
# IRPCSharedLinksPublic.UploadSharedFileCommit
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit/
Badges: `Vault API / standard` `write` `no session`
Completes an upload made with UploadSharedFile and stores the content in the checked-out file.
Used by M-Files clients; applications rarely call it.
- **Service:** [Shared links (anonymous access)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/index.md) `MFiles.IRPCSharedLinksPublic`
- **gRPC method:** `/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-shared-file-commit`
- **Request:** [`UploadSharedFileCommitRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit/index.md#request)
- **Response:** [`UploadSharedFileCommitResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFileCommit/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- The object must be checked out. The number of bytes uploaded must match the
`total_size_in_bytes` given with the first block.
## Request: UploadSharedFileCommitRequest
> Nested 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 vault GUID. |
| `access_key` | `string` | The access key of the editing link. |
| `upload_id` | `int32` | The upload ID from UploadSharedFile. |
| `low_digest` | `int64` | If not zero, the first 8 bytes of the MD5 checksum of the uploaded file, as a little-endian integer. |
| `high_digest` | `int64` | If not zero, the last 8 bytes of the MD5 checksum, as a little-endian integer. |
## Response: UploadSharedFileCommitResponse
No fields.
## Related methods
- [UploadSharedFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSharedLinksPublic/UploadSharedFile/index.md): Uploads a block of new content for a file opened for editing in Office for the web. Used by M-Files clients; applications rarely call it.
---
# Events and notifications (IRPCEvents)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/
Reads and sets the user's notification switch, checks whether a user can receive
notifications, and sends requests and custom notifications to users.
- **gRPC service:** `MFiles.IRPCEvents`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 7
- **Proto file:** [`mfiles/IRPCEvents.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCEvents.proto)
## Overview
Everything here ends in an e-mail notification, so it works only when notifications are enabled
on the server and in the vault. Several methods are used mainly by M-Files clients.
- **The caller's own on/off switch** for notifications:
[GetNotificationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/GetNotificationConfiguration/index.md),
[SetNotificationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SetNotificationConfiguration/index.md).
- **Check that a user can receive notifications**:
[TestMessageToUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/TestMessageToUser/index.md).
- **Send an e-mail** with your own subject and body:
[SendCustomNotification](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SendCustomNotification/index.md).
- **Send a request** to users:
[CreateEventFreeRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventFreeRequest/index.md),
[CreateEventCheckInRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventCheckInRequest/index.md).
Which events notify whom is defined by notification rules: see
[IRPCNotificationRules](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNotificationRules/index.md). All methods need a vault session.
Users and groups are identified by their IDs in the vault.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [CreateEventAssignRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventAssignRequest/index.md) | Not available: fails with "Not implemented.". | `write` `session` `returns metadata structure version` |
| [CreateEventCheckInRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventCheckInRequest/index.md) | Asks the user who has an object checked out to check it in. Used by M-Files clients; applications rarely call it. | `write` `session` `returns metadata structure version` |
| [CreateEventFreeRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventFreeRequest/index.md) | Sends a request with a free-text message to users and groups. Used by M-Files clients; applications rarely call it. | `write` `session` `returns metadata structure version` |
| [GetNotificationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/GetNotificationConfiguration/index.md) | Tells whether the caller has notifications turned on. | `read` `session` `idempotent` `returns metadata structure version` |
| [SendCustomNotification](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SendCustomNotification/index.md) | Sends an e-mail with the given subject and body to users, groups and e-mail addresses. | `write` `session` `returns metadata structure version` |
| [SetNotificationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SetNotificationConfiguration/index.md) | Turns notifications on or off for the caller. | `write` `session` `idempotent` `returns metadata structure version` |
| [TestMessageToUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/TestMessageToUser/index.md) | Checks whether a user can receive notifications, and fails with the reason when not. | `write` `session` `returns metadata structure version` |
---
# IRPCEvents.CreateEventAssignRequest
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventAssignRequest/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Not available: fails with "Not implemented.".
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/CreateEventAssignRequest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-event-assign-request`
- **Request:** [`CreateEventAssignRequestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventAssignRequest/index.md#request)
- **Response:** [`CreateEventAssignRequestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventAssignRequest/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
Kept for compatibility. To assign work to users, create an assignment object with
[AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md).
## Request: CreateEventAssignRequestRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `objid` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The document that is concerned by this request. |
| `objid.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). |
| `objid.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`. |
| `objid.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `objid.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. |
| `users[]` | repeated `int32` | The users who receive the request. |
| `groups[]` | repeated `int32` | The groups who receive the request. |
## Response: CreateEventAssignRequestResponse
No fields.
## Related methods
- [IRPCObjectOperations.AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
---
# IRPCEvents.CreateEventCheckInRequest
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventCheckInRequest/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Asks the user who has an object checked out to check it in. Used by M-Files clients;
applications rarely call it.
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/CreateEventCheckInRequest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-event-check-in-request`
- **Request:** [`CreateEventCheckInRequestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventCheckInRequest/index.md#request)
- **Response:** [`CreateEventCheckInRequestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventCheckInRequest/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session. No special vault rights are needed.
- The request goes to the user who has the latest version checked out. If the object is not
checked out, or event logging is disabled in the vault, the call succeeds and does nothing.
- The recipient is notified by e-mail when notifications are enabled.
## Request: CreateEventCheckInRequestRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `objid` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that should be checked in. |
| `objid.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). |
| `objid.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`. |
| `objid.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `objid.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. |
## Response: CreateEventCheckInRequestResponse
No fields.
---
# IRPCEvents.CreateEventFreeRequest
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventFreeRequest/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Sends a request with a free-text message to users and groups. Used by M-Files clients;
applications rarely call it.
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/CreateEventFreeRequest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-event-free-request`
- **Request:** [`CreateEventFreeRequestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventFreeRequest/index.md#request)
- **Response:** [`CreateEventFreeRequestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/CreateEventFreeRequest/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session; anonymous sessions get "Access denied.".
- The request is recorded as an `EVENT_TYPE_FREE_REQUEST` event addressed to the recipients
(groups are expanded to their members), only if the vault's event log configuration records
that event type. The recipients are notified by e-mail when notifications are enabled.
## Request: CreateEventFreeRequestRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `text` | `string` | The message of the request. |
| `users[]` | repeated `int32` | The IDs of the recipient user accounts. |
| `groups[]` | repeated `int32` | The IDs of the recipient user groups. |
## Response: CreateEventFreeRequestResponse
No fields.
---
# IRPCEvents.GetNotificationConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/GetNotificationConfiguration/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Tells whether the caller has notifications turned on.
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/GetNotificationConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-notification-configuration`
- **Request:** [`GetNotificationConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/GetNotificationConfiguration/index.md#request)
- **Response:** [`GetNotificationConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/GetNotificationConfiguration/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Only `is_enabled` is used; the other flags are always false here.
## Request: GetNotificationConfigurationRequest
No fields.
## Response: GetNotificationConfigurationResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pflags` | [`NOTIFICATIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NOTIFICATIONFLAGS/index.md) | The caller's notification switch. `is_enabled` is true when the caller receives notifications. |
| `pflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `pflags.is_enabled` | `bool` | Notifications enabled. |
| `pflags.send_digest` | `bool` | Combine the day's notifications into a single message. |
| `pflags.exclude_self_triggered` | `bool` | Exclude notifications of events caused by me. |
| `pflags.recurring` | `bool` | Notifications are recurring (not only appear once per a matching object). |
---
# IRPCEvents.SendCustomNotification
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SendCustomNotification/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Sends an e-mail with the given subject and body to users, groups and e-mail addresses.
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/SendCustomNotification`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/send-custom-notification`
- **Request:** [`SendCustomNotificationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SendCustomNotification/index.md#request)
- **Response:** [`SendCustomNotificationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SendCustomNotification/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session of a user. Adding `external_recipients`, or setting
`send_with_server_email_identity`, also requires the server right `send_server_messages`
([ServerAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md)); without it the call fails with "Access
denied.".
- Groups are expanded to their members. Each user and each external address gets its own
e-mail. Messages are queued when the call commits.
- The call succeeds and sends nothing when notifications are disabled on the server or in the
vault, or when the vault does not allow custom notifications.
- Sent as the caller's e-mail address, which must then be valid; or, with
`send_with_server_email_identity`, from the server's notification address with the caller's
address as reply-to.
- An external address that is not a valid e-mail address fails the whole call.
## Request: SendCustomNotificationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `uugidarr[]` | repeated [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The recipient users and user groups. |
| `uugidarr[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `uugidarr[].id` | `int32` | User or user group. |
| `include_substitute_users` | `bool` | True to also send to the substitute users of the recipient users. |
| `external_recipients[]` | repeated `string` | Additional recipients as e-mail addresses, for example `name@example.com`. Requires the server right `send_server_messages`. |
| `send_with_server_email_identity` | `bool` | True to send from the server's notification address instead of the caller's own address. Requires the server right `send_server_messages`. |
| `subject` | `string` | The subject of the e-mail. |
| `body` | `string` | The body of the e-mail. |
## Response: SendCustomNotificationResponse
No fields.
---
# IRPCEvents.SetNotificationConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SetNotificationConfiguration/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Turns notifications on or off for the caller.
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/SetNotificationConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-notification-configuration`
- **Request:** [`SetNotificationConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SetNotificationConfiguration/index.md#request)
- **Response:** [`SetNotificationConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/SetNotificationConfiguration/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed. Affects only the caller.
- Only `is_enabled` may be set; any other flag fails with "The parameter is incorrect.".
## Request: SetNotificationConfigurationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `flags` | [`NOTIFICATIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NOTIFICATIONFLAGS/index.md) | Set `is_enabled` to true to receive notifications, or leave all flags unset to stop them. |
| `flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `flags.is_enabled` | `bool` | Notifications enabled. |
| `flags.send_digest` | `bool` | Combine the day's notifications into a single message. |
| `flags.exclude_self_triggered` | `bool` | Exclude notifications of events caused by me. |
| `flags.recurring` | `bool` | Notifications are recurring (not only appear once per a matching object). |
## Response: SetNotificationConfigurationResponse
No fields.
---
# IRPCEvents.TestMessageToUser
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/TestMessageToUser/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Checks whether a user can receive notifications, and fails with the reason when not.
- **Service:** [Events and notifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/index.md) `MFiles.IRPCEvents`
- **gRPC method:** `/MFiles.IRPCEvents/TestMessageToUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/test-message-to-user`
- **Request:** [`TestMessageToUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/TestMessageToUser/index.md#request)
- **Response:** [`TestMessageToUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEvents/TestMessageToUser/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session; anonymous sessions get "Access denied.".
- Checks, in this order: notifications are enabled on the server, notifications are enabled in
the vault, event logging is enabled in the vault, the user has not turned notifications off
(only with `test_notifications_disabled_by_user`), and the user has a valid e-mail address.
The first failed check is the error, for example "Please ask your M-Files admin to enable
notifications on the M-Files server.".
- Nothing is sent. `send_message` true fails with "Not implemented.".
## Request: TestMessageToUserRequest
> Nested 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_id` | `int32` | The ID of the user account to check, or -1 for the caller. |
| `test_notifications_disabled_by_user` | `bool` | True to also fail when the user has turned notifications off. Leave false to check only whether requests can reach the user. |
| `send_message` | `bool` | Must be false; sending a test message is not supported. |
## Response: TestMessageToUserResponse
No fields.
---
# Event log (IRPCEventLog)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/
Writes custom entries to the vault's event log.
- **gRPC service:** `MFiles.IRPCEventLog`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCEventLog.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCEventLog.proto)
## Overview
Applications and vault applications use
[AddCustomEventEntry](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/AddCustomEventEntry/index.md) to record their own
auditable events next to the events that M-Files Server writes itself (logins, object changes,
administrative changes). Reading and exporting the event log are administrative operations and
are not part of this service.
- Requires a vault session whose user has the vault right `generate_event_logs`
([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)).
- Nothing is written while event logging is disabled in the vault; the call still succeeds.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AddCustomEventEntry](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/AddCustomEventEntry/index.md) | Adds a custom entry to the vault's event log and returns its event ID. | `write` `session` |
---
# IRPCEventLog.AddCustomEventEntry
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Event log](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/AddCustomEventEntry/
Badges: `Vault API / standard` `write` `session`
Adds a custom entry to the vault's event log and returns its event ID.
- **Service:** [Event log](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/index.md) `MFiles.IRPCEventLog`
- **gRPC method:** `/MFiles.IRPCEventLog/AddCustomEventEntry`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-custom-event-entry`
- **Request:** [`AddCustomEventEntryRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/AddCustomEventEntry/index.md#request)
- **Response:** [`AddCustomEventEntryResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventLog/AddCustomEventEntry/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `generate_event_logs`; otherwise the call fails with an access
denied error.
- The entry is recorded as a custom event with the current time and the calling user's account
and name.
- The event data is stored as a `customevent` XML element whose `customeventtype` attribute is
`event_type`. If `xml_data` is well-formed XML, its root element becomes a child of that
element; any other text is stored as the element's text value.
- When event logging is disabled in the vault, nothing is written and `event_id` is 0.
- Not idempotent: every successful call adds a new entry.
## Request: AddCustomEventEntryRequest
> Nested 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_type` | `string` | An identifier of your choice for the kind of event, for example `"MyApp.ContractApproved"`. Stored as the `customeventtype` attribute of the entry. |
| `xml_data` | `string` | The event data: either an XML document (stored as XML) or plain text (stored as text). May be empty. |
## Response: AddCustomEventEntryResponse
> Nested 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_id` | `int64` | The ID of the new event log entry, or 0 if event logging is disabled. |
---
# Thumbnails (IRPCThumbnails)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/
Gets thumbnail images of document files and the vault's thumbnail settings.
Provides methods for getting thumbnail-spefific information and operations.
- **gRPC service:** `MFiles.IRPCThumbnails`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCThumbnails.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCThumbnails.proto)
## Overview
Use [GetDocumentFileThumbnail](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/index.md) to show
a small picture of a file in a listing or a larger preview of its first page. All images are
PNG.
- **Classic thumbnails** (`THUMBNAIL_TYPE_CLASSIC`) are square images that the server generates
once per file version with the file type handlers installed on the server, and then caches.
Whether one exists is reported in `thumbnail_status`; not every file type has one.
- **Preview thumbnails** (`THUMBNAIL_TYPE_PREVIEW`) show the first page of the file in its own
aspect ratio, scaled to fit the size you ask for. When no preview can be made, the server
returns the file type's icon instead.
- [GetThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md) tells whether
thumbnails are enabled in the vault and which file types are excluded. M-Files desktop
clients use it to decide whether to create classic thumbnails themselves.
Both methods need a vault session and no special vault rights. To identify a file, take the
`file_ver` of a [File](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) from the object version, for example from
[GetObjectFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectFiles/index.md) or from the `files` of a
search result.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetDocumentFileThumbnail](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/index.md) | Gets a classic thumbnail or a first-page preview of one file of an object version, as PNG. | `read` `session` `idempotent` `returns metadata structure version` |
| [GetThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md) | Gets the vault's thumbnail settings. | `read` `session` `idempotent` `returns metadata structure version` |
---
# IRPCThumbnails.GetDocumentFileThumbnail
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets a classic thumbnail or a first-page preview of one file of an object version, as PNG.
- **Service:** [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md) `MFiles.IRPCThumbnails`
- **gRPC method:** `/MFiles.IRPCThumbnails/GetDocumentFileThumbnail`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-document-file-thumbnail`
- **Request:** [`GetDocumentFileThumbnailRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/index.md#request)
- **Response:** [`GetDocumentFileThumbnailResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session.
- **Classic** (`THUMBNAIL_TYPE_CLASSIC` or `THUMBNAIL_TYPE_CLASSIC_NO_ICON`; the server treats
them the same): identify the file with a specific file version (`FILE_VER_TYPE_SPECIFIC`). The
server generates the thumbnail on first request and caches it. Check `thumbnail_status`:
- `THUMBNAIL_STATUS_GENERATED`: `thumbnail` holds the PNG.
- `THUMBNAIL_STATUS_CANNOT_GENERATE`: the server has no thumbnail handler for the file type.
- `THUMBNAIL_STATUS_FAILED_TO_GENERATE`, `THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE`:
generation failed, or the file's data is missing.
- `THUMBNAIL_STATUS_DO_NOT_GENERATE`: thumbnails are turned off, or the file type is excluded
(see [GetThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md)).
- `THUMBNAIL_STATUS_NOT_GENERATED`: no thumbnail yet.
In every case other than `THUMBNAIL_STATUS_GENERATED`, `thumbnail` is empty: show an icon or
ask for a preview instead.
- **Preview** (`THUMBNAIL_TYPE_PREVIEW`): `obj_ver` must name a specific version
(`OBJ_VER_VERSION_TYPE_SPECIFIC`); a latest-version reference fails. The file must belong to
that version. The server renders the first page and scales it to fit within `max_width` x
`max_height`, keeping the aspect ratio; images are at most 999 pixels on the longer side.
The response has `thumbnail_type` `THUMBNAIL_TYPE_PREVIEW`. If no preview can be made, the
response holds the file type's icon instead, with `thumbnail_type` `THUMBNAIL_TYPE_CLASSIC`;
`thumbnail_status` is `THUMBNAIL_STATUS_GENERATED` in both cases.
- The first preview of a file can take a while, because the server first makes a PDF version
of the file. Later calls reuse it.
- Previews work only for files stored in the vault; for files of external repositories the
call fails with "Not implemented.".
## Request: GetDocumentFileThumbnailRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version that has the file. For a preview, a specific version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its specific version, as in the [File](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) entries of the object version. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `type` | [`ThumbnailType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ThumbnailType/index.md) | `THUMBNAIL_TYPE_CLASSIC` (default) for the cached square thumbnail, or `THUMBNAIL_TYPE_PREVIEW` for a first-page preview. Values: `THUMBNAIL_TYPE_CLASSIC` (0), `THUMBNAIL_TYPE_CLASSIC_NO_ICON` (1), `THUMBNAIL_TYPE_PREVIEW` (2). |
| `max_width` | `uint32` | For a preview, the largest width in pixels. Ignored for classic thumbnails. |
| `max_height` | `uint32` | For a preview, the largest height in pixels. Ignored for classic thumbnails. With both `max_width` and `max_height` 0, the server uses a default size. |
## Response: GetDocumentFileThumbnailResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `thumbnail_status` | [`ThumbnailStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ThumbnailStatus/index.md) | Whether a thumbnail was returned: `THUMBNAIL_STATUS_GENERATED` means `thumbnail` has data. See the remarks for the other values. Values: `THUMBNAIL_STATUS_NO_ACTIONS_ALLOWED` (0), `THUMBNAIL_STATUS_NOT_GENERATED` (1), `THUMBNAIL_STATUS_GENERATED` (2), `THUMBNAIL_STATUS_DO_NOT_GENERATE` (3), `THUMBNAIL_STATUS_CANNOT_GENERATE` (4), `THUMBNAIL_STATUS_FAILED_TO_GENERATE` (5), `THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE` (6). |
| `thumbnail_type` | [`ThumbnailType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ThumbnailType/index.md) | The kind of image returned: `THUMBNAIL_TYPE_PREVIEW` for a page preview, `THUMBNAIL_TYPE_CLASSIC` for a classic thumbnail or a file type icon. Values: `THUMBNAIL_TYPE_CLASSIC` (0), `THUMBNAIL_TYPE_CLASSIC_NO_ICON` (1), `THUMBNAIL_TYPE_PREVIEW` (2). |
| `thumbnail` | `bytes` | The image as PNG bytes. Empty unless `thumbnail_status` is `THUMBNAIL_STATUS_GENERATED`. |
## Related methods
- [GetThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md): Gets the vault's thumbnail settings.
---
# IRPCThumbnails.GetThumbnailOptions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the vault's thumbnail settings.
- **Service:** [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md) `MFiles.IRPCThumbnails`
- **gRPC method:** `/MFiles.IRPCThumbnails/GetThumbnailOptions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-thumbnail-options`
- **Request:** [`GetThumbnailOptionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md#request)
- **Response:** [`GetThumbnailOptionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- `is_thumbnail_feature_on` false means that the server returns no classic thumbnails
(`THUMBNAIL_STATUS_DO_NOT_GENERATE`) and clients should not create them either.
- `size` is the size of the classic thumbnails that the server generates, 256 x 256 pixels by
default.
- `denied_file_extensions` lists the file extensions (without the dot) for which thumbnails
must not be generated.
## Request: GetThumbnailOptionsRequest
No fields.
## Response: GetThumbnailOptionsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pthumbops` | [`ThumbnailOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ThumbnailOptions/index.md) | The thumbnail settings of the vault. See [ThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ThumbnailOptions/index.md). |
| `pthumbops.is_thumbnail_feature_on` | `bool` | True if the whole Thumbnails feature is on. If off, neiher the server nor the client generates thumbnails. |
| `pthumbops.is_client_side_generation_on` | `bool` | True if the client-side thumbnail generation is on. If off, the server still generates thumbnails if bThumbnailFeatureOn is true. |
| `pthumbops.size` | [`Size`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Size/index.md) | The size of thumbnails generated and cached by server. |
| `pthumbops.size.width` | `int32` | |
| `pthumbops.size.height` | `int32` | |
| `pthumbops.denied_file_extensions[]` | repeated `string` | An array of file extensions (not including dot) for which thumbnail generation is not allowed. |
---
# Languages (IRPCLanguages)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/
Lists the vault's metadata languages and changes the calling user's vault language.
Provides methods for read-only access to languages.
- **gRPC service:** `MFiles.IRPCLanguages`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCLanguages.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCLanguages.proto)
## Overview
A vault can have translations of its metadata structure (names of classes, properties, value
list items and so on) in several languages. Each user account has a vault language; a new
session starts in it, and the server returns translated names in the session's language.
- [GetLanguages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/index.md) lists the languages. ID 0 is the
default language of the vault, which every vault has.
- [ChangeLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/ChangeLanguage/index.md) stores another language for the
calling user and applies it to the current session immediately.
The vault language is separate from `ClientData.language` given at login. After a language
change, names that you cached from earlier responses are in the old language; read them again.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [ChangeLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/ChangeLanguage/index.md) | Changes the vault language of the calling user, for this session and later sessions. | `write` `session` `idempotent` `returns metadata structure version` |
| [GetLanguages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/index.md) | Gets the metadata languages defined in the vault. | `read` `session` `idempotent` `returns metadata structure version` |
---
# IRPCLanguages.ChangeLanguage
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Languages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/ChangeLanguage/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Changes the vault language of the calling user, for this session and later sessions.
- **Service:** [Languages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/index.md) `MFiles.IRPCLanguages`
- **gRPC method:** `/MFiles.IRPCLanguages/ChangeLanguage`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-language`
- **Request:** [`ChangeLanguageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/ChangeLanguage/index.md#request)
- **Response:** [`ChangeLanguageResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/ChangeLanguage/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed. Anonymous sessions cannot
change the language ("Access denied.").
- The language is stored in the user's account, so the user's later sessions start in it. The
current session switches immediately: later calls return names in the new
language.
- A language ID that does not exist fails with "Not found.".
- Setting the language that the user already has succeeds and changes nothing.
## Request: ChangeLanguageRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `language` | `int32` | The ID of the new language, from [GetLanguages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/index.md). 0 is the vault's default language. |
## Response: ChangeLanguageResponse
No fields.
---
# IRPCLanguages.GetLanguages
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Languages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the metadata languages defined in the vault.
- **Service:** [Languages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/index.md) `MFiles.IRPCLanguages`
- **gRPC method:** `/MFiles.IRPCLanguages/GetLanguages`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-languages`
- **Request:** [`GetLanguagesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/index.md#request)
- **Response:** [`GetLanguagesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Always contains the default language, ID 0. A [Language](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) with ID 0 has
an empty `language_code`.
- Language names are in the session's vault language.
## Request: GetLanguagesRequest
No fields.
## Response: GetLanguagesResponse
> Nested 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 [`Language`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) | The languages of the vault. Use the `id` with [ChangeLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/ChangeLanguage/index.md). |
| `values[].id` | `int32` | Language ID. |
| `values[].name` | `string` | The name of the language. |
| `values[].language_code` | `string` | Language indentifier, e.g. the ISO 639-1 or ISO 639-2 language code such as "en" or "eng". |
---
# Named access control lists (IRPCNamedACLs)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/
Lists the named access control lists that the calling user can see.
Provides methods for read-only access to named ACLs.
- **gRPC service:** `MFiles.IRPCNamedACLs`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCNamedACLs.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCNamedACLs.proto)
## Overview
A named access control list (named ACL) is a reusable, named set of permissions that
administrators define in the vault, such as "Visible to company management only". Users pick
one when they set the permissions of an object. Use
[GetNamedACLs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md) to fill a permissions picker or to resolve a named ACL ID that you find in an
[AccessControlList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md).
The service is read-only. Creating and editing named ACLs is an administrative operation. For
how permissions work, see
[Permissions](https://developer.m-files.com/APIs/gRPC-API/concepts/permissions/index.md).
## Methods
| Method | Summary | Facts |
|---|---|---|
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
---
# IRPCNamedACLs.GetNamedACLs
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Named access control lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/
Badges: `Vault API / standard` `read` `session or assertion` `idempotent` `returns metadata structure version`
Gets the named ACLs of the given types that the calling user is allowed to see.
- **Service:** [Named access control lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/index.md) `MFiles.IRPCNamedACLs`
- **gRPC method:** `/MFiles.IRPCNamedACLs/GetNamedACLs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-named-acls`
- **Request:** [`GetNamedACLsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md#request)
- **Response:** [`GetNamedACLsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed; named ACLs that the user is not
allowed to see are left out.
- `types` is a bit mask of [NACLType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) values and must not be 0: with 0
the call succeeds but returns nothing. Use 1 (`NACLTYPE_NORMAL`) for the named ACLs that users
can select, 2 (`NACLTYPE_INTERNAL`) for those that the vault uses for internal purposes,
or 3 for both.
- Built-in named ACLs have negative IDs, for example -1 "Full control for all internal users"
and -20 "Only for me". They are returned only with `include_builtin`.
- "Current user" entries in the returned ACLs are replaced with the calling user, so "Only for
me" contains the caller's own user ID.
- Names are in the session's vault language when translations exist. The order of the results
is not specified.
- Cacheable: the response carries the metadata structure version trailer, see
[Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).
## Request: GetNamedACLsRequest
> Nested 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_builtin` | `bool` | True to include the built-in named ACLs (negative IDs), such as "Only for me". They cannot be modified. |
| `types` | `uint32` | Bit mask of [NACLType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) values: 1 for normal, 2 for internal, 3 for both. 0 returns nothing. |
## Response: GetNamedACLsResponse
> 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_acls[]` | repeated [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The named ACLs; see [NamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md). `acl_for_objects` is the permission set that the named ACL applies to objects. |
| `named_acls[].id` | `int32` | Named ACL ID. |
| `named_acls[].name` | `string` | The name of the named ACL. |
| `named_acls[].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_acls[].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_acls[].acl_for_objects.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_acls[].acl_for_objects.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_acls[].acl_for_objects.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_acls[].acl_for_objects.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_acls[].acl_for_objects.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_acls[].acl_for_objects.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_acls[].guid` | `string` | GUID for the NACL. |
---
# Named value storage (IRPCNamedValueStorage)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/
Reads and writes named values: small key-value settings stored in the vault, grouped by
storage type and namespace.
- **gRPC service:** `MFiles.IRPCNamedValueStorage`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCNamedValueStorage.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCNamedValueStorage.proto)
## Overview
Named value storage keeps configuration and state for applications, vault applications and
M-Files itself. A value is addressed by three things:
1. **Storage type** ([NamedValueType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NamedValueType/index.md)): decides who can read and
write, and whether the value is shared or private to one user.
2. **Namespace**: a string of at most 100 characters, for example `"MyCompany.MyApp"`. Choose
one that is unique to your application.
3. **Key**: the `key` of a [NamedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md), at most 100 characters. The
value is a [TypedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md), usually `DATATYPE_TEXT` or
`DATATYPE_MULTILINE_TEXT` holding the setting as text.
Use the same spelling and case for namespaces and keys every time; keys that differ only in
case are stored as separate values.
| Storage type | Who can read | Who can write and remove |
| --- | --- | --- |
| `NAMED_VALUE_TYPE_USER_CONFIGURATION_VALUE` | any user | any user (shared by all users) |
| `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` | the user only | the user only (private to each user) |
| `NAMED_VALUE_TYPE_METADATA_CONFIGURATION_VALUE` | any user | vault right `change_metadata_structure` |
| `NAMED_VALUE_TYPE_FOLDER_CONFIGURATION_VALUE` | any user | vault right `manage_common_views` |
| `NAMED_VALUE_TYPE_ADMIN_CONFIGURATION_VALUE` | vault right `read_all_metadata_structure` | vault right `change_metadata_structure` |
| `NAMED_VALUE_TYPE_SYSTEM_CONFIGURATION_VALUE` | system administrators | `change_metadata_structure` and full server rights |
| `NAMED_VALUE_TYPE_REGISTRY_VALUE` | any user | nobody (read-only) |
`NAMED_VALUE_TYPE_PROPERTY_AUTOMATIC_NUMBERING` and `NAMED_VALUE_TYPE_VAULT_SHARED_VARIABLE`
are not accessible through this service ("Access denied."), and
`NAMED_VALUE_TYPE_UNINITIALIZED` fails with "The parameter is incorrect.". Anonymous sessions
cannot set values. Vault rights are in [VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md).
Some namespaces of the configuration types hold M-Files' own vault configuration, such as vault
settings and metadata card configuration. Writing to them changes how the vault behaves and can
change the metadata structure version. Do not write to namespaces that your application does not own.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetNamedValues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/GetNamedValues/index.md) | Gets all named values of one storage type and namespace. | `read` `session` `idempotent` `returns metadata structure version` |
| [RemoveNamedValues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/RemoveNamedValues/index.md) | Removes named values from one namespace by key. | `write` `session` `returns metadata structure version` |
| [SetNamedValues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/SetNamedValues/index.md) | Creates or replaces the given named values in one namespace, optionally only if the current values are as expected. | `write` `session` `idempotent` `returns metadata structure version` |
---
# IRPCNamedValueStorage.GetNamedValues
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/GetNamedValues/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets all named values of one storage type and namespace.
- **Service:** [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md) `MFiles.IRPCNamedValueStorage`
- **gRPC method:** `/MFiles.IRPCNamedValueStorage/GetNamedValues`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-named-values`
- **Request:** [`GetNamedValuesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/GetNamedValues/index.md#request)
- **Response:** [`GetNamedValuesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/GetNamedValues/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session; the read rights depend on `storage_type` (see the service
overview). A storage type the caller cannot read fails with "Access denied.".
- Returns every value in the namespace, sorted by key. An unknown namespace returns an empty
list, not an error.
- With `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` only the calling user's own values are returned.
- A namespace longer than 100 characters fails with "The parameter is incorrect. (Too long
namespace.)".
## Request: GetNamedValuesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `storage_type` | [`NamedValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NamedValueType/index.md) | The storage type to read. See the table in the service overview. Values: `NAMED_VALUE_TYPE_UNINITIALIZED` (0), `NAMED_VALUE_TYPE_PROPERTY_AUTOMATIC_NUMBERING` (1), `NAMED_VALUE_TYPE_VAULT_SHARED_VARIABLE` (2), `NAMED_VALUE_TYPE_METADATA_CONFIGURATION_VALUE` (3), `NAMED_VALUE_TYPE_USER_CONFIGURATION_VALUE` (4), `NAMED_VALUE_TYPE_REGISTRY_VALUE` (5), `NAMED_VALUE_TYPE_FOLDER_CONFIGURATION_VALUE` (6), `NAMED_VALUE_TYPE_ADMIN_CONFIGURATION_VALUE` (7), `NAMED_VALUE_TYPE_SYSTEM_CONFIGURATION_VALUE` (8), `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` (9). |
| `namespace_name` | `string` | The namespace, for example `"MyCompany.MyApp"`. |
## Response: GetNamedValuesResponse
> Nested 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 [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | The values of the namespace, sorted by key. |
| `values[].key` | `string` | The name of the value. |
| `values[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `values[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `values[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `values[].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. |
---
# IRPCNamedValueStorage.RemoveNamedValues
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/RemoveNamedValues/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Removes named values from one namespace by key.
- **Service:** [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md) `MFiles.IRPCNamedValueStorage`
- **gRPC method:** `/MFiles.IRPCNamedValueStorage/RemoveNamedValues`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-named-values`
- **Request:** [`RemoveNamedValuesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/RemoveNamedValues/index.md#request)
- **Response:** [`RemoveNamedValuesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/RemoveNamedValues/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session; the write rights depend on `storage_type` (see the service
overview).
- Keys that do not exist are ignored; the call succeeds.
- With `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` only the calling user's own values are removed.
## Request: RemoveNamedValuesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `storage_type` | [`NamedValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NamedValueType/index.md) | The storage type of the values. Values: `NAMED_VALUE_TYPE_UNINITIALIZED` (0), `NAMED_VALUE_TYPE_PROPERTY_AUTOMATIC_NUMBERING` (1), `NAMED_VALUE_TYPE_VAULT_SHARED_VARIABLE` (2), `NAMED_VALUE_TYPE_METADATA_CONFIGURATION_VALUE` (3), `NAMED_VALUE_TYPE_USER_CONFIGURATION_VALUE` (4), `NAMED_VALUE_TYPE_REGISTRY_VALUE` (5), `NAMED_VALUE_TYPE_FOLDER_CONFIGURATION_VALUE` (6), `NAMED_VALUE_TYPE_ADMIN_CONFIGURATION_VALUE` (7), `NAMED_VALUE_TYPE_SYSTEM_CONFIGURATION_VALUE` (8), `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` (9). |
| `namespace_name` | `string` | The namespace of the values. |
| `keys[]` | repeated `string` | The keys of the values to remove. |
## Response: RemoveNamedValuesResponse
No fields.
---
# IRPCNamedValueStorage.SetNamedValues
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/SetNamedValues/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Creates or replaces the given named values in one namespace, optionally only if the current
values are as expected.
- **Service:** [Named value storage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/index.md) `MFiles.IRPCNamedValueStorage`
- **gRPC method:** `/MFiles.IRPCNamedValueStorage/SetNamedValues`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-named-values`
- **Request:** [`SetNamedValuesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/SetNamedValues/index.md#request)
- **Response:** [`SetNamedValuesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/SetNamedValues/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session; the write rights depend on `storage_type` (see the service
overview). Anonymous sessions get "Access denied.".
- Only the keys in `values` are written; other keys in the namespace stay as they are. Each
written key gets the new value as a whole.
- **Optimistic concurrency** with `required_existing_value`: every listed key must currently
have exactly the listed value, or, if the listed value is empty, must have no value. If any of
them differs, nothing is written and the call fails with "An SQL update statement yielded a
probable lock conflict." (0x800403F9). Read the values again, merge and retry.
- If no value would change, nothing is written.
- With `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` the values are stored for the calling user only.
## Request: SetNamedValuesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `storage_type` | [`NamedValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NamedValueType/index.md) | The storage type to write. See the table in the service overview. Values: `NAMED_VALUE_TYPE_UNINITIALIZED` (0), `NAMED_VALUE_TYPE_PROPERTY_AUTOMATIC_NUMBERING` (1), `NAMED_VALUE_TYPE_VAULT_SHARED_VARIABLE` (2), `NAMED_VALUE_TYPE_METADATA_CONFIGURATION_VALUE` (3), `NAMED_VALUE_TYPE_USER_CONFIGURATION_VALUE` (4), `NAMED_VALUE_TYPE_REGISTRY_VALUE` (5), `NAMED_VALUE_TYPE_FOLDER_CONFIGURATION_VALUE` (6), `NAMED_VALUE_TYPE_ADMIN_CONFIGURATION_VALUE` (7), `NAMED_VALUE_TYPE_SYSTEM_CONFIGURATION_VALUE` (8), `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` (9). |
| `namespace_name` | `string` | The namespace, at most 100 characters. |
| `values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | The values to create or replace. Keys are at most 100 characters. |
| `values[].key` | `string` | The name of the value. |
| `values[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `values[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `values[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `values[].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. |
| `required_existing_value[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Optional. Values that must be current before the write, typically the values you read with [GetNamedValues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedValueStorage/GetNamedValues/index.md). A key with an empty value means "must not exist". On a mismatch the call fails with 0x800403F9 and nothing is written. |
| `required_existing_value[].key` | `string` | The name of the value. |
| `required_existing_value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `required_existing_value[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `required_existing_value[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `required_existing_value[].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. |
## Response: SetNamedValuesResponse
No fields.
---
# Workspaces (IRPCWorkspace)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/
Workspace tabs: the views of related objects shown for an object of a given type.
- **gRPC service:** `MFiles.IRPCWorkspace`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCWorkspace.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCWorkspace.proto)
## Overview
Supports workspaces: the tabs that a client shows for an object of a given object type, each tab
being a view of related objects (for example the projects and contacts of a customer). Used by
M-Files clients that show workspaces; applications rarely call it.
How the parts fit together:
- A workspace tab is a view that lists objects of a target object type related to the object of
the source object type. The server keeps, per source and target object type pair, one hidden
filter-only view under which the tab views live.
- [CreateTemporaryWorkspaceView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/CreateTemporaryWorkspaceView/index.md)
returns ready-made definitions of a new tab view and of its reverse-direction view. Save the
one you want with [AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md).
- [GetWorkspaceSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/GetWorkspaceSettings/index.md) and
[SetWorkspaceSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/SetWorkspaceSettings/index.md) read and store the
order of the tabs, per user and as a default for all users.
All three methods fail with "Not implemented." on servers where workspaces are not enabled.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [CreateTemporaryWorkspaceView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/CreateTemporaryWorkspaceView/index.md) | Builds the definitions of a new workspace tab view and its reverse view for a pair of object types, without saving the views. | `write` `session or assertion` `returns metadata structure version` |
| [GetWorkspaceSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/GetWorkspaceSettings/index.md) | Gets the tab order of the workspace of an object type: the caller's effective order, or the default for all users. | `write` `session or assertion` `returns metadata structure version` |
| [SetWorkspaceSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/SetWorkspaceSettings/index.md) | Stores the tab order of the workspace of an object type for the caller or as the default for all users, or resets the caller's order. | `write` `session or assertion` `returns metadata structure version` |
---
# IRPCWorkspace.CreateTemporaryWorkspaceView
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/CreateTemporaryWorkspaceView/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Builds the definitions of a new workspace tab view and its reverse view for a pair of object
types, without saving the views.
- **Service:** [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md) `MFiles.IRPCWorkspace`
- **gRPC method:** `/MFiles.IRPCWorkspace/CreateTemporaryWorkspaceView`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-temporary-workspace-view`
- **Request:** [`CreateTemporaryWorkspaceViewRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/CreateTemporaryWorkspaceView/index.md#request)
- **Response:** [`CreateTemporaryWorkspaceViewResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/CreateTemporaryWorkspaceView/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Both IDs must be real object types; a value list fails with "The parameter is incorrect.".
- The returned views are not saved and have no name. They are located under the pair's
filter-only view and give read access to all users. Set the name and any other fields, then
save a view with [AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md).
- Side effect: the first call for a pair of object types creates and saves the pair's hidden
filter-only view, which later calls reuse.
## Request: CreateTemporaryWorkspaceViewRequest
> Nested 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_object_type_id` | `int32` | The object type of the object whose workspace shows the tab. |
| `target_object_type_id` | `int32` | The object type of the related objects that the tab lists. |
## Response: CreateTemporaryWorkspaceViewResponse
> 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 |
|---|---|---|
| `view` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The tab view, not yet saved. |
| `view.id` | `int32` | The ID of the view. |
| `view.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). |
| `view.name` | `string` | The name of the view. |
| `view.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `view.is_visible` | `bool` | Tells if the view is visible. |
| `view.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. |
| `view.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. |
| `view.location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `view.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. |
| `view.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. |
| `view.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. |
| `view.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). |
| `view.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. |
| `view.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `view.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. |
| `view.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. |
| `view.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. |
| `view.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. |
| `view.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. |
| `view.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. |
| `view.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `view.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. |
| `view.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `view.options.indexed` | `bool` | Materialized/indexed view. |
| `view.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. |
| `view.options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `view.guid` | `string` | GUID for the view. |
| `view.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `view.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. |
| `reverse` | [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The view in the reverse direction, not yet saved. |
| `reverse.id` | `int32` | The ID of the view. |
| `reverse.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). |
| `reverse.name` | `string` | The name of the view. |
| `reverse.is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `reverse.is_visible` | `bool` | Tells if the view is visible. |
| `reverse.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. |
| `reverse.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. |
| `reverse.location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `reverse.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. |
| `reverse.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. |
| `reverse.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. |
| `reverse.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). |
| `reverse.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. |
| `reverse.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `reverse.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. |
| `reverse.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. |
| `reverse.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. |
| `reverse.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. |
| `reverse.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. |
| `reverse.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. |
| `reverse.flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `reverse.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. |
| `reverse.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `reverse.options.indexed` | `bool` | Materialized/indexed view. |
| `reverse.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. |
| `reverse.options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `reverse.guid` | `string` | GUID for the view. |
| `reverse.view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `reverse.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. |
## Related methods
- [IRPCViews.AddNewView](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/AddNewView/index.md): Creates a new private or common view.
---
# IRPCWorkspace.GetWorkspaceSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/GetWorkspaceSettings/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Gets the tab order of the workspace of an object type: the caller's effective order, or the
default for all users.
- **Service:** [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md) `MFiles.IRPCWorkspace`
- **gRPC method:** `/MFiles.IRPCWorkspace/GetWorkspaceSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-workspace-settings`
- **Request:** [`GetWorkspaceSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/GetWorkspaceSettings/index.md#request)
- **Response:** [`GetWorkspaceSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/GetWorkspaceSettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- `WORKSPACE_SETTINGS_SCOPE_EFFECTIVE` (default) returns the caller's own order, or the default
order when the caller has none. `WORKSPACE_SETTINGS_SCOPE_DEFAULTS` returns the default order,
limited to common views.
- The stored order is reconciled with the tab views that exist and that the caller can see:
views that no longer exist are dropped and new views are appended. When nothing is stored,
`view_ids` lists all visible tab views.
- An object type without workspace views, or an unknown ID, returns empty `view_ids`.
## Request: GetWorkspaceSettingsRequest
> Nested 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_id` | `int32` | The source object type of the workspace. |
| `scope` | [`WorkspaceSettingsScope`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.WorkspaceSettingsScope/index.md) | Which order to return. Leave unset (`WORKSPACE_SETTINGS_SCOPE_EFFECTIVE`) for the caller's own effective order. Values: `WORKSPACE_SETTINGS_SCOPE_EFFECTIVE` (0), `WORKSPACE_SETTINGS_SCOPE_DEFAULTS` (1). |
## Response: GetWorkspaceSettingsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `workspace_settings` | [`WorkspaceSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkspaceSettings/index.md) | The tab view IDs in display order. |
| `workspace_settings.view_ids[]` | repeated `int32` | View IDs in order. |
---
# IRPCWorkspace.SetWorkspaceSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/SetWorkspaceSettings/
Badges: `Vault API / standard` `write` `session or assertion` `returns metadata structure version`
Stores the tab order of the workspace of an object type for the caller or as the default for
all users, or resets the caller's order.
- **Service:** [Workspaces](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/index.md) `MFiles.IRPCWorkspace`
- **gRPC method:** `/MFiles.IRPCWorkspace/SetWorkspaceSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-workspace-settings`
- **Request:** [`SetWorkspaceSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/SetWorkspaceSettings/index.md#request)
- **Response:** [`SetWorkspaceSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkspace/SetWorkspaceSettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. The actions `WORKSPACE_SETTINGS_ACTION_SET_AS_DEFAULT_TO_ALL_USERS`
and `WORKSPACE_SETTINGS_ACTION_SET_AS_DEFAULT_TO_ALL_USERS_OVERRIDE` also need the vault right
`manage_common_views`.
- `workspace_settings.view_ids` must not be empty except with
`WORKSPACE_SETTINGS_ACTION_RESET_TO_DEFAULT`, and every ID must be a tab view of this
workspace; otherwise the call fails with "The parameter is incorrect.". A default order may
contain only common views.
- `WORKSPACE_SETTINGS_ACTION_RESET_TO_DEFAULT` deletes the caller's own order.
`WORKSPACE_SETTINGS_ACTION_SET_AS_DEFAULT_TO_ALL_USERS_OVERRIDE` stores the default and deletes
every user's own order for this object type.
## Request: SetWorkspaceSettingsRequest
> Nested 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_id` | `int32` | The source object type of the workspace. |
| `workspace_settings_action` | [`WorkspaceSettingsAction`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.WorkspaceSettingsAction/index.md) | What to do. Leave unset (`WORKSPACE_SETTINGS_ACTION_APPLY_PERSONAL_SETTINGS`) to store the caller's own order. Values: `WORKSPACE_SETTINGS_ACTION_APPLY_PERSONAL_SETTINGS` (0), `WORKSPACE_SETTINGS_ACTION_RESET_TO_DEFAULT` (1), `WORKSPACE_SETTINGS_ACTION_SET_AS_DEFAULT_TO_ALL_USERS` (2), `WORKSPACE_SETTINGS_ACTION_SET_AS_DEFAULT_TO_ALL_USERS_OVERRIDE` (3). |
| `workspace_settings` | [`WorkspaceSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkspaceSettings/index.md) | The tab view IDs in display order. Ignored when resetting. |
| `workspace_settings.view_ids[]` | repeated `int32` | View IDs in order. |
## Response: SetWorkspaceSettingsResponse
No fields.
---
# Task pane configurations (IRPCTaskPaneConfigurations)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/
Stores the task pane configuration of M-Files Desktop per user and for all users.
- **gRPC service:** `MFiles.IRPCTaskPaneConfigurations`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCTaskPaneConfigurations.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCTaskPaneConfigurations.proto)
## Overview
Stores the task pane configuration of M-Files Desktop for each user, and a common configuration
that administrators publish for all users. Used by M-Files clients; applications rarely call it.
The configuration is an opaque blob that the client defines. The server stores it per user and
per data version and checks only its first four bytes:
- Every non-empty blob starts with its data version as a 32-bit little-endian integer, and that
value must equal the `data_version` it is saved with; otherwise saving fails with "The
parameter is incorrect.".
- An empty blob means the program defaults.
- Readers pass `max_data_version_interpretable`, the newest data version they understand. The
server returns the newest stored blob whose version is not greater; saving a version deletes
the caller's stored blobs of newer versions.
Lookup order when reading: the user's own configuration, then the common configuration, then the
program defaults (an empty blob).
## Methods
| Method | Summary | Facts |
|---|---|---|
| [LoadTaskPaneConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration/index.md) | Gets the calling user's task pane configuration, falling back to the common configuration and then to the program defaults. | `write` `session` `idempotent` `returns metadata structure version` |
| [PublishCurrentTaskPaneConfigurationAsCommonConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/PublishCurrentTaskPaneConfigurationAsCommonConfiguration/index.md) | Publishes the calling user's current task pane configuration as the common configuration for all users. | `write` `session` `idempotent` `returns metadata structure version` |
| [ResetTaskPaneConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/ResetTaskPaneConfiguration/index.md) | Resets the calling user's task pane configuration to the program defaults or to the common configuration. | `write` `session` `idempotent` `returns metadata structure version` |
| [SaveTaskPaneConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/SaveTaskPaneConfiguration/index.md) | Saves the calling user's task pane configuration. | `write` `session` `idempotent` `returns metadata structure version` |
---
# IRPCTaskPaneConfigurations.LoadTaskPaneConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Gets the calling user's task pane configuration, falling back to the common configuration and
then to the program defaults.
- **Service:** [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md) `MFiles.IRPCTaskPaneConfigurations`
- **gRPC method:** `/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/load-task-pane-configuration`
- **Request:** [`LoadTaskPaneConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration/index.md#request)
- **Response:** [`LoadTaskPaneConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Returns the newest stored blob whose data version is at most `max_data_version_interpretable`.
An empty `data` means the program defaults.
## Request: LoadTaskPaneConfigurationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `max_data_version_interpretable` | `int32` | The newest data version that the caller understands. |
## Response: LoadTaskPaneConfigurationResponse
> Nested 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 configuration blob. Its first four bytes are its data version (little-endian); empty means the program defaults. |
---
# IRPCTaskPaneConfigurations.PublishCurrentTaskPaneConfigurationAsCommonConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/PublishCurrentTaskPaneConfigurationAsCommonConfiguration/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Publishes the calling user's current task pane configuration as the common configuration for all
users.
- **Service:** [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md) `MFiles.IRPCTaskPaneConfigurations`
- **gRPC method:** `/MFiles.IRPCTaskPaneConfigurations/PublishCurrentTaskPaneConfigurationAsCommonConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/publish-current-task-pane-configuration-as-common-configuration`
- **Request:** [`PublishCurrentTaskPaneConfigurationAsCommonConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/PublishCurrentTaskPaneConfigurationAsCommonConfiguration/index.md#request)
- **Response:** [`PublishCurrentTaskPaneConfigurationAsCommonConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/PublishCurrentTaskPaneConfigurationAsCommonConfiguration/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `license_allows_modifications` and `manage_common_uisettings`;
otherwise fails with "Access denied.".
- Copies what [LoadTaskPaneConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration/index.md)
would return for the caller into the common configuration.
- With `reset_common_configuration_for_all_users` true, the server also overwrites every user's
own configuration of that data version, adds it for users who have only older versions, and
deletes newer versions, so all users get the published configuration.
## Request: PublishCurrentTaskPaneConfigurationAsCommonConfigurationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `reset_common_configuration_for_all_users` | `bool` | True to also replace the configurations of all users with the published one. |
| `max_data_version_interpretable` | `int32` | The newest data version that the caller understands. |
## Response: PublishCurrentTaskPaneConfigurationAsCommonConfigurationResponse
No fields.
## Related methods
- [LoadTaskPaneConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/LoadTaskPaneConfiguration/index.md): Gets the calling user's task pane configuration, falling back to the common configuration and then to the program defaults.
---
# IRPCTaskPaneConfigurations.ResetTaskPaneConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/ResetTaskPaneConfiguration/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Resets the calling user's task pane configuration to the program defaults or to the common
configuration.
- **Service:** [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md) `MFiles.IRPCTaskPaneConfigurations`
- **gRPC method:** `/MFiles.IRPCTaskPaneConfigurations/ResetTaskPaneConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-task-pane-configuration`
- **Request:** [`ResetTaskPaneConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/ResetTaskPaneConfiguration/index.md#request)
- **Response:** [`ResetTaskPaneConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/ResetTaskPaneConfiguration/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- With `reset_to_program_defaults` true, the user's configuration becomes empty (program
defaults). With false, the server copies the common configuration (or the program defaults if
there is none) into the user's configuration.
- Like a save, the reset deletes the user's stored configurations of newer data versions than
the one written.
## Request: ResetTaskPaneConfigurationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `reset_to_program_defaults` | `bool` | True to reset to the program defaults; false to reset to the common configuration. |
| `max_data_version_interpretable` | `int32` | The newest data version that the caller understands. |
## Response: ResetTaskPaneConfigurationResponse
No fields.
---
# IRPCTaskPaneConfigurations.SaveTaskPaneConfiguration
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/SaveTaskPaneConfiguration/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Saves the calling user's task pane configuration.
- **Service:** [Task pane configurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/index.md) `MFiles.IRPCTaskPaneConfigurations`
- **gRPC method:** `/MFiles.IRPCTaskPaneConfigurations/SaveTaskPaneConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/save-task-pane-configuration`
- **Request:** [`SaveTaskPaneConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/SaveTaskPaneConfiguration/index.md#request)
- **Response:** [`SaveTaskPaneConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTaskPaneConfigurations/SaveTaskPaneConfiguration/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- The first four bytes of `data_` must be `data_version` as a 32-bit little-endian integer, or
the call fails with "The parameter is incorrect.". An empty `data_` stores the program
defaults.
- Saving deletes the caller's stored configurations of newer data versions.
## Request: SaveTaskPaneConfigurationRequest
> Nested 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_version` | `int32` | The data version of the blob. |
| `data_` | `bytes` | The configuration blob, starting with `data_version` as a 32-bit little-endian integer. |
## Response: SaveTaskPaneConfigurationResponse
No fields.
---
# Folder UI settings (IRPCFolderUISettings)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/
Stores the display settings of folders per user and as common defaults.
- **gRPC service:** `MFiles.IRPCFolderUISettings`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 7
- **Proto file:** [`mfiles/IRPCFolderUISettings.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCFolderUISettings.proto)
## Overview
Stores the display settings of folders: which listing columns are shown and how wide, sorting,
grouping, view mode, and the layout of the panes. Settings are kept per user and folder, and an
administrator can save common settings that users get by default. Used by M-Files clients;
applications rarely call it.
A folder is identified by a [UISettingsFolderID](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md): a folder type
(`UISETTINGS_FOLDER_TYPE_...`) and, for folders inside a view, the view ID. All folders of the
same type in one view share their settings.
Two families of methods work on the same stored settings:
- **Structured state** (newer clients):
[GetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md),
[SetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/index.md) and
[ResetFolderUIStateToDefaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUIStateToDefaults/index.md)
exchange a [FolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderUIState/index.md). The get and set methods take a folder
location (a path of [Folder](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) elements from the vault root) and resolve
the folder ID on the server.
- **Opaque blobs** (M-Files Desktop):
[GetFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUISettings/index.md),
[SaveFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/index.md) and
[ResetFolderUISettingsToDefaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/index.md)
exchange the client's binary format. A non-empty blob starts with its data version as a 32-bit
little-endian integer, which must equal the version it is saved with; an empty blob means the
program defaults.
**Data versions.** Every stored setting has a data version. Readers pass
`max_data_version_interpretable`; the server returns the newest stored version that is not
greater. The structured state is stored in data version 15 on current servers.
**Lookup order** when reading a user's settings: the user's own settings, then the common
settings, then the program defaults.
**Rights.** Any user can store their own settings. Saving common settings, or resetting all users
to them, needs the vault right `manage_common_uisettings`. Common settings cannot be stored for a
folder in a user's own (not common) view, and only the owner of such a view can store settings
for its folders. Anonymous sessions cannot save settings.
[SetFolderSelection](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderSelection/index.md) stores a different
per-user setting: folders that the user wants to see on a view level whose listing is cut by the
folder limit.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUISettings/index.md) | Gets the display settings of a folder as an opaque blob. | `read` `session` `idempotent` `returns metadata structure version` |
| [GetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md) | Gets the display settings of a folder location as a structure. | `write` `session` `returns metadata structure version` |
| [ResetFolderUISettingsToDefaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/index.md) | Resets the caller's display settings of a folder to the program defaults or to the common settings, and returns the result as an opaque blob. | `write` `session` `idempotent` `returns metadata structure version` |
| [ResetFolderUIStateToDefaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUIStateToDefaults/index.md) | Resets the caller's display settings of a folder to the program defaults or to the common settings, and returns the resulting state as a structure. | `write` `session` `idempotent` `returns metadata structure version` |
| [SaveFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/index.md) | Saves the display settings of a folder as an opaque blob, for the caller and optionally as the common settings. | `write` `session` `idempotent` `returns metadata structure version` |
| [SetFolderSelection](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderSelection/index.md) | Replaces the calling user's folder selection for one view level: the folders that the user always wants to see on a level whose listing is cut by the folder limit. | `write` `session` `idempotent` `returns metadata structure version` |
| [SetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/index.md) | Saves the display settings of a folder location from a structure, for the caller and optionally as the common settings. | `write` `session` `returns metadata structure version` |
---
# IRPCFolderUISettings.GetFolderUISettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUISettings/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the display settings of a folder as an opaque blob.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/GetFolderUISettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-uisettings`
- **Request:** [`GetFolderUISettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUISettings/index.md#request)
- **Response:** [`GetFolderUISettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUISettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- With `common_settings` false, returns the caller's own settings, falling back to the common
settings and then to the program defaults (empty `data`). With true, returns the common
settings or empty `data`.
- Returns the newest stored data version that is at most `max_data_version_interpretable`.
## Request: GetFolderUISettingsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `common_settings` | `bool` | True for the common settings; false for the caller's effective settings. |
| `uisfid` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The folder. |
| `uisfid.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `uisfid.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `max_data_version_interpretable` | `int32` | The newest data version that the caller understands. |
## Response: GetFolderUISettingsResponse
> Nested 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 settings blob, starting with its data version as a 32-bit little-endian integer; empty means the program defaults. |
---
# IRPCFolderUISettings.GetFolderUIState
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Gets the display settings of a folder location as a structure.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/GetFolderUIState`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-folder-uistate`
- **Request:** [`GetFolderUIStateRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md#request)
- **Response:** [`GetFolderUIStateResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session. No special vault rights are needed.
- The server resolves the folder from `folder_location`, for example a view folder followed by
property folders. An empty location means the vault root. Set `type` for folders that a
location cannot express, such as `UISETTINGS_FOLDER_TYPE_HISTORY_UI`; the resolved ID is
returned in `folder_uistate.folder_id`.
- With `common_settings` false, returns the caller's effective settings (own, then common, then
program defaults); with true, the common settings. `program_defaults` true returns the program
defaults and overrides `common_settings`.
- Column positions in the returned listing state are not always numbered from 0: state read from
settings that older clients saved can number the visible columns from 1. Renumber them before
sending the state back with
[SetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/index.md).
## Request: GetFolderUIStateRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `common_settings` | `bool` | True for the common settings; false for the caller's effective settings. |
| `object_folder` | `bool` | True when the location is an object's folder (its files) inside `folder_location`. Prefer `type` `UISETTINGS_FOLDER_TYPE_OBJECT_FILES_CONTAINER`. |
| `folder_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The path of folders from the vault root to the folder. Empty for the root. |
| `folder_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `folder_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `folder_location[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `folder_location[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `folder_location[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `folder_location[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `folder_location[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `folder_location[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `max_data_version_interpretable` | `int32` | The newest settings data version that the caller understands. Use 15. |
| `type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The folder type, for folders whose type cannot be resolved from the location (such as the history or relationships dialogs). Leave unset to resolve it from `folder_location`. |
| `program_defaults` | `bool` | True to get the program defaults, ignoring stored and common settings. |
## Response: GetFolderUIStateResponse
A structure that specifies the response type for the GetFolderUIState 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 |
|---|---|---|
| `folder_uistate` | [`FolderUIState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderUIState/index.md) | The display settings, including the resolved `folder_id`. |
| `folder_uistate.folder_id` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The ID that describes the folder. |
| `folder_uistate.folder_id.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `folder_uistate.folder_id.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `folder_uistate.folder_type` | [`ShellFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ShellFolderType/index.md) | Specifies shell folder type. Values: `SHELL_FOLDER_TYPE_NORMAL` (0), `SHELL_FOLDER_TYPE_OBJECT_HISTORY` (2), `SHELL_FOLDER_TYPE_NON_OBJECT_ITEMS` (3), `SHELL_FOLDER_TYPE_RELATIONSHIPS` (4), `SHELL_FOLDER_TYPE_SUBOBJECTS` (5), `SHELL_FOLDER_TYPE_COLLECTION_MEMBERS` (6), `SHELL_FOLDER_TYPE_DELETED_CONFLICT_HISTORY` (7). |
| `folder_uistate.show_right_pane` | `bool` | Specifies whether the right pane is displayed. |
| `folder_uistate.show_bottom_pane` | `bool` | Specifies whether the bottom pane is displayed. |
| `folder_uistate.is_bottom_pane_minimized` | `bool` | Specifies whether the bottom pane is minimized. |
| `folder_uistate.is_right_pane_minimized` | `bool` | Specifies whether the right pane is minimized. |
| `folder_uistate.show_metadata_editorn_right_pane` | `bool` | Specifies whether the metadata editor is displayed in the right pane. If false, the metadata editor appears in the bottom pane. |
| `folder_uistate.is_hit_highlighting_enabled` | `bool` | Specifies whether hit highlighting in file content is enabled. |
| `folder_uistate.bottom_pane_height` | `int32` | Specifies the bottom pane height. The height is relative to the size of the frame window holding the bottom pane bar. |
| `folder_uistate.right_pane_width` | `int32` | Specifies the right pane width. |
| `folder_uistate.show_task_pane` | `bool` | Specifies whether the task area is displayed. |
| `folder_uistate.is_task_pane_minimized` | `bool` | Specifies whether the task area is minimized. |
| `folder_uistate.listing_ui_state` | [`FolderListingUIState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingUIState/index.md) | The listing UI state. |
| `folder_uistate.listing_ui_state.columns[]` | repeated [`FolderListingColumn`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingColumn/index.md) | The Columns. |
| `folder_uistate.listing_ui_state.column_sorting[]` | repeated [`FolderListingColumnSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingColumnSorting/index.md) | The ColumnSortings. |
| `folder_uistate.listing_ui_state.view_mode` | [`FolderListingViewMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderListingViewMode/index.md) | The listing view mode. Values: `FOLDER_LISTING_VIEW_MODE_UNINITIALIZED` (0), `FOLDER_LISTING_VIEW_MODE_ICON` (1), `FOLDER_LISTING_VIEW_MODE_SMALL_ICON` (2), `FOLDER_LISTING_VIEW_MODE_LIST` (3), `FOLDER_LISTING_VIEW_MODE_DETAILS` (4), `FOLDER_LISTING_VIEW_MODE_THUMBNAIL` (5), `FOLDER_LISTING_VIEW_MODE_TILE` (6), `FOLDER_LISTING_VIEW_MODE_THUMBSTRIP` (7), `FOLDER_LISTING_VIEW_MODE_CONTENT` (8). |
| `folder_uistate.listing_ui_state.item_grouping_mode` | [`FOLDERLISTINGITEMGROUPINGMODEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERLISTINGITEMGROUPINGMODEFLAGS/index.md) | The listing item grouping mode. |
| `folder_uistate.listing_ui_state.icon_size` | `int32` | The listing item icon size. |
| `folder_uistate.listing_ui_state.results_per_page` | `uint32` | The results per page option. |
| `has_selected_folders` | `bool` | True when the caller has a stored folder selection (see [SetFolderSelection](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderSelection/index.md)) for exactly this location. |
## Related methods
- [SetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/index.md): Saves the display settings of a folder location from a structure, for the caller and optionally as the common settings.
---
# IRPCFolderUISettings.ResetFolderUISettingsToDefaults
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Resets the caller's display settings of a folder to the program defaults or to the common
settings, and returns the result as an opaque blob.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-folder-uisettings-to-defaults`
- **Request:** [`ResetFolderUISettingsToDefaultsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/index.md#request)
- **Response:** [`ResetFolderUISettingsToDefaultsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Exactly one of `reset_to_program_defaults` and `reset_to_common_defaults` must be true;
otherwise the call fails with "The parameter is incorrect." and nothing changes.
- Resetting to the common settings copies them into the caller's own settings (or stores
program defaults if there are no common settings) and deletes the caller's settings of newer
data versions.
- Only the caller's own settings change.
## Request: ResetFolderUISettingsToDefaultsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `reset_to_program_defaults` | `bool` | True to reset to the program defaults. |
| `reset_to_common_defaults` | `bool` | True to reset to the common settings. |
| `uisfid` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The folder. |
| `uisfid.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `uisfid.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `max_data_version_interpretable` | `int32` | The newest data version that the caller understands. |
## Response: ResetFolderUISettingsToDefaultsResponse
> Nested 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 caller's settings after the reset, as returned by [GetFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUISettings/index.md). |
---
# IRPCFolderUISettings.ResetFolderUIStateToDefaults
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUIStateToDefaults/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Resets the caller's display settings of a folder to the program defaults or to the common
settings, and returns the resulting state as a structure.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/ResetFolderUIStateToDefaults`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-folder-uistate-to-defaults`
- **Request:** [`ResetFolderUIStateToDefaultsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUIStateToDefaults/index.md#request)
- **Response:** [`ResetFolderUIStateToDefaultsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUIStateToDefaults/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Behaves like
[ResetFolderUISettingsToDefaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/index.md)
but returns a [FolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderUIState/index.md), so the caller can refresh its
listing without another call.
- Exactly one of `reset_to_program_defaults` and `reset_to_common_defaults` must be true;
otherwise the call fails with "The parameter is incorrect." and nothing changes.
- The folder is given directly as a [UISettingsFolderID](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md), for
example the `folder_id` from [GetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md).
- Fails with "Not implemented." on servers where the feature is not enabled.
## Request: ResetFolderUIStateToDefaultsRequest
The request of ResetFolderUIStateToDefaults. Exactly one of `reset_to_program_defaults` and
`reset_to_common_defaults` must be true.
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `reset_to_program_defaults` | `bool` | True to reset to the program defaults. |
| `reset_to_common_defaults` | `bool` | True to reset to the common settings. |
| `uisfid` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The folder. |
| `uisfid.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `uisfid.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `max_data_version_interpretable` | `int32` | The newest settings data version that the caller understands. Use 15. |
## Response: ResetFolderUIStateToDefaultsResponse
The response of ResetFolderUIStateToDefaults: the resulting state, in the same form as the
response of GetFolderUIState.
> Nested 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_uistate` | [`FolderUIState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderUIState/index.md) | The caller's display settings after the reset. |
| `folder_uistate.folder_id` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The ID that describes the folder. |
| `folder_uistate.folder_id.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `folder_uistate.folder_id.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `folder_uistate.folder_type` | [`ShellFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ShellFolderType/index.md) | Specifies shell folder type. Values: `SHELL_FOLDER_TYPE_NORMAL` (0), `SHELL_FOLDER_TYPE_OBJECT_HISTORY` (2), `SHELL_FOLDER_TYPE_NON_OBJECT_ITEMS` (3), `SHELL_FOLDER_TYPE_RELATIONSHIPS` (4), `SHELL_FOLDER_TYPE_SUBOBJECTS` (5), `SHELL_FOLDER_TYPE_COLLECTION_MEMBERS` (6), `SHELL_FOLDER_TYPE_DELETED_CONFLICT_HISTORY` (7). |
| `folder_uistate.show_right_pane` | `bool` | Specifies whether the right pane is displayed. |
| `folder_uistate.show_bottom_pane` | `bool` | Specifies whether the bottom pane is displayed. |
| `folder_uistate.is_bottom_pane_minimized` | `bool` | Specifies whether the bottom pane is minimized. |
| `folder_uistate.is_right_pane_minimized` | `bool` | Specifies whether the right pane is minimized. |
| `folder_uistate.show_metadata_editorn_right_pane` | `bool` | Specifies whether the metadata editor is displayed in the right pane. If false, the metadata editor appears in the bottom pane. |
| `folder_uistate.is_hit_highlighting_enabled` | `bool` | Specifies whether hit highlighting in file content is enabled. |
| `folder_uistate.bottom_pane_height` | `int32` | Specifies the bottom pane height. The height is relative to the size of the frame window holding the bottom pane bar. |
| `folder_uistate.right_pane_width` | `int32` | Specifies the right pane width. |
| `folder_uistate.show_task_pane` | `bool` | Specifies whether the task area is displayed. |
| `folder_uistate.is_task_pane_minimized` | `bool` | Specifies whether the task area is minimized. |
| `folder_uistate.listing_ui_state` | [`FolderListingUIState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingUIState/index.md) | The listing UI state. |
| `folder_uistate.listing_ui_state.columns[]` | repeated [`FolderListingColumn`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingColumn/index.md) | The Columns. |
| `folder_uistate.listing_ui_state.column_sorting[]` | repeated [`FolderListingColumnSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingColumnSorting/index.md) | The ColumnSortings. |
| `folder_uistate.listing_ui_state.view_mode` | [`FolderListingViewMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderListingViewMode/index.md) | The listing view mode. Values: `FOLDER_LISTING_VIEW_MODE_UNINITIALIZED` (0), `FOLDER_LISTING_VIEW_MODE_ICON` (1), `FOLDER_LISTING_VIEW_MODE_SMALL_ICON` (2), `FOLDER_LISTING_VIEW_MODE_LIST` (3), `FOLDER_LISTING_VIEW_MODE_DETAILS` (4), `FOLDER_LISTING_VIEW_MODE_THUMBNAIL` (5), `FOLDER_LISTING_VIEW_MODE_TILE` (6), `FOLDER_LISTING_VIEW_MODE_THUMBSTRIP` (7), `FOLDER_LISTING_VIEW_MODE_CONTENT` (8). |
| `folder_uistate.listing_ui_state.item_grouping_mode` | [`FOLDERLISTINGITEMGROUPINGMODEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERLISTINGITEMGROUPINGMODEFLAGS/index.md) | The listing item grouping mode. |
| `folder_uistate.listing_ui_state.icon_size` | `int32` | The listing item icon size. |
| `folder_uistate.listing_ui_state.results_per_page` | `uint32` | The results per page option. |
## Related methods
- [ResetFolderUISettingsToDefaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/ResetFolderUISettingsToDefaults/index.md): Resets the caller's display settings of a folder to the program defaults or to the common settings, and returns the result as an opaque blob.
- [GetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md): Gets the display settings of a folder location as a structure.
---
# IRPCFolderUISettings.SaveFolderUISettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Saves the display settings of a folder as an opaque blob, for the caller and optionally as the
common settings.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/SaveFolderUISettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/save-folder-uisettings`
- **Request:** [`SaveFolderUISettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/index.md#request)
- **Response:** [`SaveFolderUISettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. With `save_as_common_settings` it also needs the vault right
`manage_common_uisettings`; otherwise the call fails with "Access denied.".
- The first four bytes of `data` must be `data_version` (32-bit little-endian), or the call fails
with "The parameter is incorrect.".
- The settings are always saved for the caller. With `save_as_common_settings` they are also
saved as the common settings. With `reset_common_settings_to_all_users` as well, every user's
own settings of this folder are overwritten, and their settings of newer data versions are
deleted.
## Request: SaveFolderUISettingsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `save_as_common_settings` | `bool` | True to also save the settings as the common settings of the folder. |
| `reset_common_settings_to_all_users` | `bool` | True to also overwrite every user's settings of the folder. Used only with `save_as_common_settings`. |
| `uisfid` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The folder. |
| `uisfid.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `uisfid.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `data_version` | `int32` | The data version of `data`. |
| `data` | `bytes` | The settings blob, starting with `data_version` as a 32-bit little-endian integer. |
## Response: SaveFolderUISettingsResponse
No fields.
---
# IRPCFolderUISettings.SetFolderSelection
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderSelection/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Replaces the calling user's folder selection for one view level: the folders that the user
always wants to see on a level whose listing is cut by the folder limit.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/SetFolderSelection`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-folder-selection`
- **Request:** [`SetFolderSelectionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderSelection/index.md#request)
- **Response:** [`SetFolderSelectionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderSelection/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Not available on servers where the feature is not enabled: fails with "Not implemented."
("Folder selection is not enabled on this server.").
- Requires a vault session of a named user; anonymous sessions get "Access denied.".
- `folder_location` must be a view folder followed only by property folders, and the level it
leads to must group by a property or value; other locations fail.
- `folders` are the property folder values as the listing returned them. Lookups are stored by
item ID only, so a renamed item stays selected. Empty values, multi-select lookups and
duplicates are rejected. The selection may not have more folders than the level's folder
limit.
- An empty `folders` clears the selection. The whole selection is replaced; a failed call leaves
the stored selection unchanged.
## Request: SetFolderSelectionRequest
Replaces the calling user's folder selection for one folder location. The selection always belongs to
the session's user, so the request has no user field. An empty folder array clears the selection.
> Nested 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_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The path from the vault root to the parent of the level whose folders are selected: a view folder followed by property folders. |
| `folder_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `folder_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `folder_location[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `folder_location[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `folder_location[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `folder_location[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `folder_location[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `folder_location[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `folders[]` | repeated [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The complete new selection, as the folder values that the listing returned. Empty clears it. |
| `folders[].is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `folders[].type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `folders[].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. |
| `folders[].data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `folders[].data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `folders[].data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `folders[].data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `folders[].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. |
| `folders[].data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `folders[].data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `folders[].data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `folders[].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. |
| `folders[].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. |
| `folders[].data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `folders[].data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `folders[].data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `folders[].data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
## Response: SetFolderSelectionResponse
A structure that specifies the response type for the SetFolderSelection 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 |
|---|---|---|
| `has_selected_folders` | `bool` | True when the caller has a stored selection for the location after the call. |
---
# IRPCFolderUISettings.SetFolderUIState
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Saves the display settings of a folder location from a structure, for the caller and optionally
as the common settings.
- **Service:** [Folder UI settings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/index.md) `MFiles.IRPCFolderUISettings`
- **gRPC method:** `/MFiles.IRPCFolderUISettings/SetFolderUIState`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-folder-uistate`
- **Request:** [`SetFolderUIStateRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/index.md#request)
- **Response:** [`SetFolderUIStateResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SetFolderUIState/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session. Saving common settings needs the vault right
`manage_common_uisettings`.
- The server resolves the folder from `folder_location` and `type` as in
[GetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md).
- Set `max_data_version_interpretable` to 15: the server stores the state in that data version
and fails with "The parameter is incorrect." for any other value.
- The listing columns are validated: the visible columns must have unique positions numbered
from 0 ("The first visible column should have position 0.", "Non-unique column position.").
Hidden columns use position -1.
- With `save_as_common_settings` and `reset_common_settings_to_all_users`, every user's settings
of the folder are overwritten, as with
[SaveFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/index.md).
## Request: SetFolderUIStateRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `save_as_common_settings` | `bool` | True to also save the state as the common settings of the folder. |
| `reset_common_settings_to_all_users` | `bool` | True to also overwrite every user's settings of the folder. Used only with `save_as_common_settings`. |
| `object_folder` | `bool` | True when the location is an object's folder (its files) inside `folder_location`. Prefer `type` `UISETTINGS_FOLDER_TYPE_OBJECT_FILES_CONTAINER`. |
| `folder_location[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | The path of folders from the vault root to the folder. Empty for the root. |
| `folder_location[].type` | [`FolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderType/index.md) | The type of the folder, for example `FOLDER_TYPE_VIEW_FOLDER` or `FOLDER_TYPE_PROPERTY_FOLDER`. Values: `FOLDER_TYPE_UNKNOWN` (0), `FOLDER_TYPE_ANY_FOLDER` (1), `FOLDER_TYPE_VIEW_FOLDER` (2), `FOLDER_TYPE_PROPERTY_FOLDER` (3), `FOLDER_TYPE_TRADITIONAL_FOLDER` (4), `FOLDER_TYPE_SEARCH_FOLDER` (5), `FOLDER_TYPE_EXTERNAL_VIEW_FOLDER` (6). |
| `folder_location[].data` | [`FolderInfoUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md) | Additional folder type -specific information as a union. |
| `folder_location[].data.any_folder` | [`FolderInfoUnion.AnyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-AnyFolderData) (oneof data) | Any folder type. |
| `folder_location[].data.view_folder` | [`FolderInfoUnion.ViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ViewFolderData) (oneof data) | View folder type. |
| `folder_location[].data.property_folder` | [`FolderInfoUnion.PropertyFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-PropertyFolderData) (oneof data) | Property (virtual) folder type. |
| `folder_location[].data.traditional_folder` | [`FolderInfoUnion.TraditionalFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-TraditionalFolderData) (oneof data) | Traditional folder type. |
| `folder_location[].data.search_folder` | [`FolderInfoUnion.SearchFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-SearchFolderData) (oneof data) | Search folder (extended view folder) type. |
| `folder_location[].data.external_view_folder` | [`FolderInfoUnion.ExternalViewFolderData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderInfoUnion/index.md#t-ExternalViewFolderData) (oneof data) | External view folder type. |
| `max_data_version_interpretable` | `int32` | The data version to store. Must be 15. |
| `folder_uistate` | [`FolderUIState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderUIState/index.md) | The display settings to store. |
| `folder_uistate.folder_id` | [`UISettingsFolderID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UISettingsFolderID/index.md) | The ID that describes the folder. |
| `folder_uistate.folder_id.type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The type that describes the folder whose UI settings are being retrieved. |
| `folder_uistate.folder_id.view` | `int32` | If not zero, specifies the view where the folder is located. |
| `folder_uistate.folder_type` | [`ShellFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ShellFolderType/index.md) | Specifies shell folder type. Values: `SHELL_FOLDER_TYPE_NORMAL` (0), `SHELL_FOLDER_TYPE_OBJECT_HISTORY` (2), `SHELL_FOLDER_TYPE_NON_OBJECT_ITEMS` (3), `SHELL_FOLDER_TYPE_RELATIONSHIPS` (4), `SHELL_FOLDER_TYPE_SUBOBJECTS` (5), `SHELL_FOLDER_TYPE_COLLECTION_MEMBERS` (6), `SHELL_FOLDER_TYPE_DELETED_CONFLICT_HISTORY` (7). |
| `folder_uistate.show_right_pane` | `bool` | Specifies whether the right pane is displayed. |
| `folder_uistate.show_bottom_pane` | `bool` | Specifies whether the bottom pane is displayed. |
| `folder_uistate.is_bottom_pane_minimized` | `bool` | Specifies whether the bottom pane is minimized. |
| `folder_uistate.is_right_pane_minimized` | `bool` | Specifies whether the right pane is minimized. |
| `folder_uistate.show_metadata_editorn_right_pane` | `bool` | Specifies whether the metadata editor is displayed in the right pane. If false, the metadata editor appears in the bottom pane. |
| `folder_uistate.is_hit_highlighting_enabled` | `bool` | Specifies whether hit highlighting in file content is enabled. |
| `folder_uistate.bottom_pane_height` | `int32` | Specifies the bottom pane height. The height is relative to the size of the frame window holding the bottom pane bar. |
| `folder_uistate.right_pane_width` | `int32` | Specifies the right pane width. |
| `folder_uistate.show_task_pane` | `bool` | Specifies whether the task area is displayed. |
| `folder_uistate.is_task_pane_minimized` | `bool` | Specifies whether the task area is minimized. |
| `folder_uistate.listing_ui_state` | [`FolderListingUIState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingUIState/index.md) | The listing UI state. |
| `folder_uistate.listing_ui_state.columns[]` | repeated [`FolderListingColumn`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingColumn/index.md) | The Columns. |
| `folder_uistate.listing_ui_state.column_sorting[]` | repeated [`FolderListingColumnSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FolderListingColumnSorting/index.md) | The ColumnSortings. |
| `folder_uistate.listing_ui_state.view_mode` | [`FolderListingViewMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FolderListingViewMode/index.md) | The listing view mode. Values: `FOLDER_LISTING_VIEW_MODE_UNINITIALIZED` (0), `FOLDER_LISTING_VIEW_MODE_ICON` (1), `FOLDER_LISTING_VIEW_MODE_SMALL_ICON` (2), `FOLDER_LISTING_VIEW_MODE_LIST` (3), `FOLDER_LISTING_VIEW_MODE_DETAILS` (4), `FOLDER_LISTING_VIEW_MODE_THUMBNAIL` (5), `FOLDER_LISTING_VIEW_MODE_TILE` (6), `FOLDER_LISTING_VIEW_MODE_THUMBSTRIP` (7), `FOLDER_LISTING_VIEW_MODE_CONTENT` (8). |
| `folder_uistate.listing_ui_state.item_grouping_mode` | [`FOLDERLISTINGITEMGROUPINGMODEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FOLDERLISTINGITEMGROUPINGMODEFLAGS/index.md) | The listing item grouping mode. |
| `folder_uistate.listing_ui_state.icon_size` | `int32` | The listing item icon size. |
| `folder_uistate.listing_ui_state.results_per_page` | `uint32` | The results per page option. |
| `type` | [`UISettingsFolderType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UISettingsFolderType/index.md) | The folder type, for folders whose type cannot be resolved from the location. Leave unset to resolve it from `folder_location`. |
## Response: SetFolderUIStateResponse
No fields.
## Related methods
- [GetFolderUIState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/GetFolderUIState/index.md): Gets the display settings of a folder location as a structure.
- [SaveFolderUISettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFolderUISettings/SaveFolderUISettings/index.md): Saves the display settings of a folder as an opaque blob, for the caller and optionally as the common settings.
---
# Substitute users (IRPCSubstituteUsers)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/
Reads and sets the substitute users of users.
- **gRPC service:** `MFiles.IRPCSubstituteUsers`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCSubstituteUsers.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCSubstituteUsers.proto)
## Overview
Reads and sets substitute users: users or user groups who act for a user, for example during an
absence. A substitute sees the assignments of the users they substitute for in views that use
the "current user and substituted users" pseudo user, such as the built-in Assigned to Me view.
- **The caller's own substitutes**:
[GetSubstituteUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsers/index.md) and
[SetSubstituteUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/SetSubstituteUsers/index.md). Any user can
manage their own list.
- **Any user's substitutes, and the reverse lookup** (administration):
[GetSubstituteUsersOfUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser/index.md) and
[GetUsersBySubstituteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetUsersBySubstituteUser/index.md). These
need the vault right `manage_users`.
The session's own view of substitution is in the login response:
`SessionData.vault_data.substitute_users` lists the session's user followed by the users that
this user currently substitutes for.
Substitution can be turned off for the whole server. Then the get methods return empty lists and
[SetSubstituteUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/SetSubstituteUsers/index.md) fails with "Access
denied.".
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetSubstituteUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsers/index.md) | Gets the substitutes of the calling user. | `read` `session` `idempotent` `returns metadata structure version` |
| [GetSubstituteUsersOfUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser/index.md) | Gets the substitutes of any user (administration). | `read` `session` `idempotent` `returns metadata structure version` |
| [GetUsersBySubstituteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetUsersBySubstituteUser/index.md) | Gets the users for whom a given user is a substitute, directly or through group membership (administration). | `read` `session` `idempotent` `returns metadata structure version` |
| [SetSubstituteUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/SetSubstituteUsers/index.md) | Replaces the substitutes of the calling user. | `write` `session` `idempotent` `returns metadata structure version` |
---
# IRPCSubstituteUsers.GetSubstituteUsers
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsers/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the substitutes of the calling user.
- **Service:** [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md) `MFiles.IRPCSubstituteUsers`
- **gRPC method:** `/MFiles.IRPCSubstituteUsers/GetSubstituteUsers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-substitute-users`
- **Request:** [`GetSubstituteUsersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsers/index.md#request)
- **Response:** [`GetSubstituteUsersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsers/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- The list contains users and user groups, in no specified order. It is empty when the user has
no substitutes or substitution is turned off on the server.
## Request: GetSubstituteUsersRequest
No fields.
## Response: GetSubstituteUsersResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `substitutes[]` | repeated [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The users (`USER_TYPE_USER`) and user groups (`USER_TYPE_USER_GROUP`) who substitute for the caller. |
| `substitutes[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `substitutes[].id` | `int32` | User or user group. |
## Related methods
- [GetSubstituteUsersOfUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser/index.md): Gets the substitutes of any user (administration).
---
# IRPCSubstituteUsers.GetSubstituteUsersOfUser
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the substitutes of any user (administration).
- **Service:** [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md) `MFiles.IRPCSubstituteUsers`
- **gRPC method:** `/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-substitute-users-of-user`
- **Request:** [`GetSubstituteUsersOfUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser/index.md#request)
- **Response:** [`GetSubstituteUsersOfUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsersOfUser/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `manage_users`; other users get "Access denied.".
- An unknown user ID returns an empty list.
## Request: GetSubstituteUsersOfUserRequest
> Nested 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_id` | `int32` | The ID of the user whose substitutes are wanted. |
## Response: GetSubstituteUsersOfUserResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `substitutes[]` | repeated [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The users and user groups who substitute for that user. |
| `substitutes[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `substitutes[].id` | `int32` | User or user group. |
## Related methods
- [GetSubstituteUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetSubstituteUsers/index.md): Gets the substitutes of the calling user.
---
# IRPCSubstituteUsers.GetUsersBySubstituteUser
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetUsersBySubstituteUser/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets the users for whom a given user is a substitute, directly or through group membership
(administration).
- **Service:** [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md) `MFiles.IRPCSubstituteUsers`
- **gRPC method:** `/MFiles.IRPCSubstituteUsers/GetUsersBySubstituteUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users-by-substitute-user`
- **Request:** [`GetUsersBySubstituteUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetUsersBySubstituteUser/index.md#request)
- **Response:** [`GetUsersBySubstituteUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/GetUsersBySubstituteUser/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `manage_users`; other users get "Access denied.".
- A user is returned when the given user, or any group that the given user belongs to directly
or indirectly, is among that user's substitutes. The given user is never returned.
- Pass the ID of an existing user.
## Request: GetUsersBySubstituteUserRequest
> Nested 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_id` | `int32` | The ID of the substitute user. |
## Response: GetUsersBySubstituteUserResponse
> Nested 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 [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The users (`USER_TYPE_USER`) for whom `user_id` is a substitute. |
| `users[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `users[].id` | `int32` | User or user group. |
---
# IRPCSubstituteUsers.SetSubstituteUsers
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/SetSubstituteUsers/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Replaces the substitutes of the calling user.
- **Service:** [Substitute users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/index.md) `MFiles.IRPCSubstituteUsers`
- **gRPC method:** `/MFiles.IRPCSubstituteUsers/SetSubstituteUsers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-substitute-users`
- **Request:** [`SetSubstituteUsersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/SetSubstituteUsers/index.md#request)
- **Response:** [`SetSubstituteUsersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSubstituteUsers/SetSubstituteUsers/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. Any user can set their own substitutes; there is no way to set
another user's substitutes with this service.
- The list replaces the old one completely: send all substitutes, and an empty list to remove
them all. Duplicates are stored once.
- Take the IDs from the Users (6) and User groups (16) value lists.
- The change takes effect at once, also for the existing sessions of the new and removed
substitutes; they do not need to log in again.
- Fails with "Access denied." when substitution is turned off on the server.
## Request: SetSubstituteUsersRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `substitutes[]` | repeated [`UserOrUserGroupID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserOrUserGroupID/index.md) | The complete new list of substitutes: users (`USER_TYPE_USER`) and user groups (`USER_TYPE_USER_GROUP`). |
| `substitutes[].type` | [`UserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserType/index.md) | User type. Values: `USER_TYPE_UNKNOWN` (0), `USER_TYPE_USER` (1), `USER_TYPE_USER_GROUP` (2), `USER_TYPE_WORKFLOW_STATE_PSEUDO_USER` (3), `USER_TYPE_PROPERTY_BASED_PSEUDO_USER` (4). |
| `substitutes[].id` | `int32` | User or user group. |
## Response: SetSubstituteUsersResponse
No fields.
---
# Electronic signatures (IRPCElectronicSignatures)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/
An interface for working with electronic signatures.
- **gRPC service:** `MFiles.IRPCElectronicSignatures`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCElectronicSignatures.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCElectronicSignatures.proto)
## Overview
Administrative repair operations for electronic signatures that are stored as separate signature
objects. Users sign by running a workflow state transition that requires an electronic
signature; these two methods only add placeholder signatures to an object or detach signatures
from it, for example to fix an object whose signatures are out of step with its workflow.
- [AddEmptyElectronicSignature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/AddEmptyElectronicSignature/index.md)
creates unsigned (empty) signature objects for the signatures that the object's workflow
defines.
- [DisconnectElectronicSignature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/DisconnectElectronicSignature/index.md)
removes signatures from the object, optionally marking them invalidated.
Prerequisites shared by both methods:
- The caller needs the vault rights `license_allows_modifications`, `see_all_objects` and
`edit_and_delete_all_objects` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)). Normal users get
"Access denied.".
- The vault must have the metadata structure for separate signature objects: an object type
with the alias `M-Files.QMS.Signature.ObjectType` and property definitions such as
`M-Files.QMS.Signatures` (the object's reference to its signatures),
`M-Files.QMS.Signature.Identifier`, `M-Files.QMS.Signature.Signer`,
`M-Files.QMS.Signature.Reason` and `M-Files.QMS.Signature.Meaning`. Without it the calls fail
with "Not found." naming the missing alias.
- `obj_ver` must name a specific version (`OBJ_VER_VERSION_TYPE_SPECIFIC`); the latest-version
form fails with "The parameter is incorrect.".
- A signature is identified by the `signature_identifier` of the state transition that requires
it (`StateTransition.signature_settings.signature_identifier`, see
[ElectronicSignatureSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md)).
Both methods update the object's signatures property like a property change and return the
object after the change.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AddEmptyElectronicSignature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/AddEmptyElectronicSignature/index.md) | Adds empty (unsigned) separate signature objects to an object for one signature, or for all signatures that its workflow requires. | `write` `session` `returns metadata structure version` |
| [DisconnectElectronicSignature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/DisconnectElectronicSignature/index.md) | Removes one signature, or all signatures, from an object's signature references, optionally invalidating the removed signature objects. | `write` `session` `returns metadata structure version` |
---
# IRPCElectronicSignatures.AddEmptyElectronicSignature
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Electronic signatures](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/AddEmptyElectronicSignature/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Adds empty (unsigned) separate signature objects to an object for one signature, or for all
signatures that its workflow requires.
- **Service:** [Electronic signatures](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/index.md) `MFiles.IRPCElectronicSignatures`
- **gRPC method:** `/MFiles.IRPCElectronicSignatures/AddEmptyElectronicSignature`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-empty-electronic-signature`
- **Request:** [`AddEmptyElectronicSignatureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/AddEmptyElectronicSignature/index.md#request)
- **Response:** [`AddEmptyElectronicSignatureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/AddEmptyElectronicSignature/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires the vault rights listed in the service overview, and read and edit access to the
object.
- The object must have a workflow; otherwise the call fails because the Workflow property is
not set.
- With an empty `signature_identifier_can_be_null`, the server adds a signature for every state
transition of the object's workflow whose signature settings are required and stored as a
separate signature object. With an identifier, it adds only that signature; an identifier that
no transition of the workflow uses fails with "Not found.", and one used by several
transitions fails as ambiguous.
- A signature that the object already references is not added again.
## Request: AddEmptyElectronicSignatureRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to update. Must be a specific version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `signature_identifier_can_be_null` | `string` | The signature identifier of one state transition, or empty to add all required signatures of the object's workflow. |
## Response: AddEmptyElectronicSignatureResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_obj_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The object after the operation. |
| `ext_obj_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_obj_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_obj_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_obj_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_obj_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_obj_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_obj_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_obj_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_obj_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_obj_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_obj_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_obj_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_obj_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_obj_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_obj_info.object_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 object (e.g. is the object deleted or a stub). |
| `ext_obj_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_obj_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_obj_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_obj_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_obj_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_obj_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_obj_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_obj_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_obj_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_obj_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_obj_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_obj_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_obj_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_obj_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_obj_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Other objects that the server updated during the operation. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# IRPCElectronicSignatures.DisconnectElectronicSignature
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Electronic signatures](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/DisconnectElectronicSignature/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Removes one signature, or all signatures, from an object's signature references, optionally
invalidating the removed signature objects.
- **Service:** [Electronic signatures](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/index.md) `MFiles.IRPCElectronicSignatures`
- **gRPC method:** `/MFiles.IRPCElectronicSignatures/DisconnectElectronicSignature`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/disconnect-electronic-signature`
- **Request:** [`DisconnectElectronicSignatureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/DisconnectElectronicSignature/index.md#request)
- **Response:** [`DisconnectElectronicSignatureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCElectronicSignatures/DisconnectElectronicSignature/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires the vault rights listed in the service overview.
- With `invalidate` false, the signature objects are only detached from the object. With
`invalidate` true, they are also marked invalidated.
## Request: DisconnectElectronicSignatureRequest
> Nested 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_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version to update. Must be a specific version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.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_ver.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_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `signature_identifier_can_be_null` | `string` | The signature identifier to remove, or empty to remove all signatures of the object. |
| `invalidate` | `bool` | True to also mark the removed signature objects invalidated. |
## Response: DisconnectElectronicSignatureResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `ext_obje_info` | [`ExtObjectInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtObjectInfo/index.md) | The object after the operation. |
| `ext_obje_info.is_visible` | `bool` | True if any version of the object is visible to the caller. |
| `ext_obje_info.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information, if `is_visible` is true. |
| `ext_obje_info.object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `ext_obje_info.object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `ext_obje_info.object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `ext_obje_info.object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `ext_obje_info.object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `ext_obje_info.object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `ext_obje_info.object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `ext_obje_info.object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `ext_obje_info.object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `ext_obje_info.object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `ext_obje_info.object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `ext_obje_info.object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `ext_obje_info.object_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 object (e.g. is the object deleted or a stub). |
| `ext_obje_info.object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `ext_obje_info.object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `ext_obje_info.object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `ext_obje_info.object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `ext_obje_info.object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `ext_obje_info.object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `ext_obje_info.is_latest_version_visible` | `bool` | True if the latest version of the object is visible to the caller. |
| `ext_obje_info.latest_version` | [`ObjectVersionExWP`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionExWP/index.md) | The latest version of the object with its properties and ACL, if `is_latest_version_visible` is true. Some methods (for example UndoCheckout) return it without property values. |
| `ext_obje_info.latest_version.object_version` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Object info. |
| `ext_obje_info.latest_version.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values, or an empty array. |
| `ext_obje_info.latest_version.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, ACL. |
| `ext_obje_info.latest_version.current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | If set, permissions of the object version. |
| `ext_obje_info.original_obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version the request named, as sent. The version part may be unset. |
| `ext_obje_info.original_obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `ext_obje_info.original_obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `updated_objects[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Other objects that the server updated during the operation. |
| `updated_objects[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `updated_objects[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `updated_objects[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `updated_objects[].version_info.title` | `string` | The title (name) of the object in this version. |
| `updated_objects[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `updated_objects[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `updated_objects[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `updated_objects[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `updated_objects[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `updated_objects[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `updated_objects[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `updated_objects[].version_info.class_id` | `int32` | The class ID of the version. |
| `updated_objects[].version_info.version_guid` | `string` | The GUID of this version. |
| `updated_objects[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `updated_objects[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `updated_objects[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `updated_objects[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `updated_objects[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `updated_objects[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `updated_objects[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `updated_objects[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `updated_objects[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `updated_objects[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `updated_objects[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `updated_objects[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `updated_objects[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `updated_objects[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `updated_objects[].object_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 object (e.g. is the object deleted or a stub). |
| `updated_objects[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `updated_objects[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `updated_objects[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `updated_objects[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `updated_objects[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
---
# Sensitivity labels (IRPCSensitivityLabels)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/
Reads the Microsoft Purview sensitivity labels of files.
- **gRPC service:** `MFiles.IRPCSensitivityLabels`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCSensitivityLabels.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCSensitivityLabels.proto)
## Overview
Reads the Microsoft Purview sensitivity labels of a file, for showing them next to the file in a
user interface. The labels come from the Microsoft SharePoint Embedded storage where the vault
keeps the file; vaults that do not store files there have no labels.
The call is advisory: it never fails because labels are unavailable. Whenever the server cannot
produce labels, it returns an empty `label_info`. Do not use it as a security check.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetSensitivityLabels](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/GetSensitivityLabels/index.md) | Gets the sensitivity labels of one file, or an empty list when no labels are available. | `read` `session` `idempotent` |
---
# IRPCSensitivityLabels.GetSensitivityLabels
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Sensitivity labels](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/GetSensitivityLabels/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets the sensitivity labels of one file, or an empty list when no labels are available.
- **Service:** [Sensitivity labels](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/index.md) `MFiles.IRPCSensitivityLabels`
- **gRPC method:** `/MFiles.IRPCSensitivityLabels/GetSensitivityLabels`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-sensitivity-labels`
- **Request:** [`GetSensitivityLabelsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/GetSensitivityLabels/index.md#request)
- **Response:** [`GetSensitivityLabelsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSensitivityLabels/GetSensitivityLabels/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed, and the server does not look up
the object that the file belongs to.
- The server reads only `file.master_storage_file_ref` and `file.extension`. Pass a
[File](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) as returned with an object version.
- `label_info.labels` is empty when any of these holds: the feature is not enabled on the
server, the vault does not store files in SharePoint Embedded, `master_storage_file_ref` is
empty, the extension is not one that carries labels, or the storage service fails or answers
with something the server cannot parse.
- Labels are looked up only for Word, Excel and PowerPoint formats (for example `docx`, `xlsx`,
`pptx` and their older and macro-enabled variants) and `pdf`. The extension is compared
case-insensitively.
## Request: GetSensitivityLabelsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The file to query. Only `master_storage_file_ref` and `extension` are read. |
| `file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `file.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file.file_ver.internal_version` | `int32` | The file version number. |
| `file.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file.title` | `string` | The file name without the extension. |
| `file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file.guid` | `string` | GUID of the file. |
| `file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `file.is_missing` | `bool` | True, if the file is missing. |
| `file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `file.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `file.flags.can_be_edited_externally` | `bool` | Next available value. |
| `file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
## Response: GetSensitivityLabelsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `label_info` | [`FileSensitivityLabelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSensitivityLabelInfo/index.md) | The labels of the file. An empty `labels` list means that no label information is available, not that the file is known to be unlabeled. |
| `label_info.labels[]` | repeated [`FileSensitivityLabel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSensitivityLabel/index.md) | Labels attached to the file. |
| `label_info.labels[].label_id` | `string` | Stable identifier of the label. May be null. |
| `label_info.labels[].label_name` | `string` | Human-readable display name. May be null. |
| `label_info.labels[].tooltip` | `string` | Hover tooltip text. May be null. |
| `label_info.labels[].color` | `string` | Color hint (e.g. "#FF0000"). May be null. |
| `label_info.labels[].has_protection` | `bool` | TRUE if the label applies encryption/rights-protection. Defaults to FALSE when absent. |
---
# Exported data sets (IRPCExportedDataSets)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/
Reads the exported data sets of the vault and reports their export status (M-Files Reporting).
- **gRPC service:** `MFiles.IRPCExportedDataSets`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 7
- **Proto file:** [`mfiles/IRPCExportedDataSets.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCExportedDataSets.proto)
## Overview
An exported data set describes which objects and properties M-Files Reporting copies from the
vault to an external reporting database. The data sets are created and changed with the
administration service [IRPCExportedDataSetsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md);
this service lets a vault session read them, start an export and follow its progress.
- **Read the data sets**:
[GetExportedDataSets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSets/index.md),
[GetExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSet/index.md).
- **Start an export now** and watch it:
[TriggerExportedDataSetRefresh](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/index.md),
then [GetDataSetExportingStatusBasic](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/index.md).
- **Used by the export process itself**:
[GetDataSetAuxiliaryExecutionControlState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/index.md),
[GetDataSetExportingReferenceTimestamp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp/index.md)
and [UpdateExportedDataSetExecutionStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/UpdateExportedDataSetExecutionStatus/index.md).
Applications rarely need them.
**Prerequisites.** Every method needs a vault session. All methods except
[GetDataSetExportingReferenceTimestamp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp/index.md)
need the Reporting module in the server or vault license; without it they fail with a "no
license for reporting" error, except
[GetExportedDataSets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSets/index.md), which returns an
empty list. Data set IDs that do not exist fail with "Not found.".
The objects and values that an export reads are available to any session through
[IRPCDataExport](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md).
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetDataSetAuxiliaryExecutionControlState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/index.md) | Gets when an export of the data set was last requested or cancelled by hand. Used by the export process. | `read` `session` `idempotent` |
| [GetDataSetExportingReferenceTimestamp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp/index.md) | Gets the current server time, as the reference time for data set synchronization. | `read` `session` `idempotent` |
| [GetDataSetExportingStatusBasic](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/index.md) | Tells whether a data set is being exported right now and when its export status last changed. | `read` `session` `idempotent` |
| [GetExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSet/index.md) | Gets one exported data set by ID. | `read` `session` `idempotent` |
| [GetExportedDataSets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSets/index.md) | Gets all exported data sets of the vault. | `read` `session` `idempotent` |
| [TriggerExportedDataSetRefresh](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/index.md) | Asks for an export of the data set to start now, outside its schedule. | `write` `session` `idempotent` |
| [UpdateExportedDataSetExecutionStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/UpdateExportedDataSetExecutionStatus/index.md) | Stores the progress of an export. Reserved for the M-Files Reporting export process. | `write` `session` `idempotent` |
---
# IRPCExportedDataSets.GetDataSetAuxiliaryExecutionControlState
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets when an export of the data set was last requested or cancelled by hand. Used by the export
process.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-data-set-auxiliary-execution-control-state`
- **Request:** [`GetDataSetAuxiliaryExecutionControlStateRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/index.md#request)
- **Response:** [`GetDataSetAuxiliaryExecutionControlStateResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Used by the M-Files Reporting export process to notice manual export and cancel requests;
applications rarely call it.
- Requires a vault session and the Reporting module in the license. An unknown ID fails with
"Not found.".
## Request: GetDataSetAuxiliaryExecutionControlStateRequest
> Nested 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. |
## Response: GetDataSetAuxiliaryExecutionControlStateResponse
> Nested 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_manual_execution_triggered` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When an export was last requested with [TriggerExportedDataSetRefresh](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/index.md) or the administration service. Unset if never. |
| `last_manual_execution_cancelled` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When an export was last cancelled. Unset if never. |
| `current` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The current server time, to compare the timestamps with. |
---
# IRPCExportedDataSets.GetDataSetExportingReferenceTimestamp
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets the current server time, as the reference time for data set synchronization.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-data-set-exporting-reference-timestamp`
- **Request:** [`GetDataSetExportingReferenceTimestampRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp/index.md#request)
- **Response:** [`GetDataSetExportingReferenceTimestampResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingReferenceTimestamp/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. Does not need the Reporting module.
## Request: GetDataSetExportingReferenceTimestampRequest
No fields.
## Response: GetDataSetExportingReferenceTimestampResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `current` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The current server time. |
---
# IRPCExportedDataSets.GetDataSetExportingStatusBasic
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/
Badges: `Vault API / standard` `read` `session` `idempotent`
Tells whether a data set is being exported right now and when its export status last changed.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-data-set-exporting-status-basic`
- **Request:** [`GetDataSetExportingStatusBasicRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/index.md#request)
- **Response:** [`GetDataSetExportingStatusBasicResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires a vault session and the Reporting module in the license. Fails if the data set is
disabled, and with "Not found." for an unknown ID.
- `exporting` is true while the export process reports progress (0-100) for the data set, and
false once it has reported that the export is not running.
- Compare `latest_activity` with `current` (both server time) to see how recent the status is.
## Request: GetDataSetExportingStatusBasicRequest
> Nested 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. |
## Response: GetDataSetExportingStatusBasicResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `exporting` | `bool` | True if the data set is being exported. |
| `current` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The current server time. |
| `latest_activity` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the export process last updated the status of the data set. Unset if it never has. |
---
# IRPCExportedDataSets.GetExportedDataSet
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSet/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets one exported data set by ID.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/GetExportedDataSet`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-data-set`
- **Request:** [`GetExportedDataSetRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSet/index.md#request)
- **Response:** [`GetExportedDataSetResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSet/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires a vault session and the Reporting module in the license. An unknown ID fails with
"Not found.".
- `database_connection_string` is empty unless the user has the vault right `see_all_objects`.
## Request: GetExportedDataSetRequest
> Nested 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 exported data set. |
## Response: GetExportedDataSetResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pexpdataset` | [`ExportedDataSet`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md) | The exported data set. See [ExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md). |
| `pexpdataset.id` | `int32` | Exported data set ID. |
| `pexpdataset.name` | `string` | The name of the data set. |
| `pexpdataset.object_types[]` | repeated [`ExportedDataObjectType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataObjectType/index.md) | Root nodes representing an object type. |
| `pexpdataset.object_types[].object_type` | `int32` | Object type or value list ID. |
| `pexpdataset.object_types[].property_defs[]` | repeated [`ExportedDataPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataPropertyDef/index.md) | Child property definition nodes. |
| `pexpdataset.object_types[].object_filter` | [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | The filtering conditions that limit the object set of this node. |
| `pexpdataset.options` | [`EXPORTEDDATASETFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXPORTEDDATASETFLAGS/index.md) | Data set flags. |
| `pexpdataset.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `pexpdataset.options.disabled` | `bool` | Present if the data set is disabled. If not present, the data set is enabled. |
| `pexpdataset.options.scheduled` | `bool` | Present if the data set execution is scheduled. |
| `pexpdataset.options.incremental` | `bool` | Exported data set flags. |
| `pexpdataset.schedule` | `bytes` | The schedule of this data set extraction (a serialized Task object of Task Scheduler). |
| `pexpdataset.database_connection_string` | `string` | The database connection string. |
| `pexpdataset.run_as_user_id` | `int32` | "Run as" user id for the exported data set. |
| `pexpdataset.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). |
---
# IRPCExportedDataSets.GetExportedDataSets
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSets/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets all exported data sets of the vault.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/GetExportedDataSets`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-data-sets`
- **Request:** [`GetExportedDataSetsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSets/index.md#request)
- **Response:** [`GetExportedDataSetsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetExportedDataSets/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires a vault session; no special vault rights.
- Returns an empty list when the license does not include the Reporting module.
- `database_connection_string` is empty unless the user has the vault right `see_all_objects`
([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)).
## Request: GetExportedDataSetsRequest
No fields.
## Response: GetExportedDataSetsResponse
> Nested 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 [`ExportedDataSet`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md) | The exported data sets. See [ExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md). |
| `results[].id` | `int32` | Exported data set ID. |
| `results[].name` | `string` | The name of the data set. |
| `results[].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[].object_types[].object_type` | `int32` | Object type or value list ID. |
| `results[].object_types[].property_defs[]` | repeated [`ExportedDataPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataPropertyDef/index.md) | Child property definition nodes. |
| `results[].object_types[].object_filter` | [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | The filtering conditions that limit the object set of this node. |
| `results[].options` | [`EXPORTEDDATASETFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXPORTEDDATASETFLAGS/index.md) | Data set flags. |
| `results[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `results[].options.disabled` | `bool` | Present if the data set is disabled. If not present, the data set is enabled. |
| `results[].options.scheduled` | `bool` | Present if the data set execution is scheduled. |
| `results[].options.incremental` | `bool` | Exported data set flags. |
| `results[].schedule` | `bytes` | The schedule of this data set extraction (a serialized Task object of Task Scheduler). |
| `results[].database_connection_string` | `string` | The database connection string. |
| `results[].run_as_user_id` | `int32` | "Run as" user id for the exported data set. |
| `results[].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). |
---
# IRPCExportedDataSets.TriggerExportedDataSetRefresh
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/
Badges: `Vault API / standard` `write` `session` `idempotent`
Asks for an export of the data set to start now, outside its schedule.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/trigger-exported-data-set-refresh`
- **Request:** [`TriggerExportedDataSetRefreshRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/index.md#request)
- **Response:** [`TriggerExportedDataSetRefreshResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `trigger_data_export` and the Reporting module in the license.
- Fails if the data set is disabled, and with "Not found." for an unknown ID.
- The call only records the time of the request (returned as `last_manual_execution_triggered`
by [GetDataSetAuxiliaryExecutionControlState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/index.md));
the export process notices it and runs the export. Follow the progress with
[GetDataSetExportingStatusBasic](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/index.md).
- Cancel a running export with the administration service
([CancelExportedDataSetExecution](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution/index.md)).
## Request: TriggerExportedDataSetRefreshRequest
> Nested 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. |
## Response: TriggerExportedDataSetRefreshResponse
No fields.
## Related methods
- [GetDataSetAuxiliaryExecutionControlState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetAuxiliaryExecutionControlState/index.md): Gets when an export of the data set was last requested or cancelled by hand. Used by the export process.
- [GetDataSetExportingStatusBasic](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/GetDataSetExportingStatusBasic/index.md): Tells whether a data set is being exported right now and when its export status last changed.
- [IRPCExportedDataSetsAdmin.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.
---
# IRPCExportedDataSets.UpdateExportedDataSetExecutionStatus
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/UpdateExportedDataSetExecutionStatus/
Badges: `Vault API / standard` `write` `session` `idempotent`
Stores the progress of an export. Reserved for the M-Files Reporting export process.
- **Service:** [Exported data sets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md) `MFiles.IRPCExportedDataSets`
- **gRPC method:** `/MFiles.IRPCExportedDataSets/UpdateExportedDataSetExecutionStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-exported-data-set-execution-status`
- **Request:** [`UpdateExportedDataSetExecutionStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/UpdateExportedDataSetExecutionStatus/index.md#request)
- **Response:** [`UpdateExportedDataSetExecutionStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/UpdateExportedDataSetExecutionStatus/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- The server accepts the call only from a session of a local system administrator of the
server machine. Other sessions, including vault administrators connected over gRPC, get
"Access denied.".
- Fails if the data set is disabled.
## Request: UpdateExportedDataSetExecutionStatusRequest
> Nested 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. |
| `progress_percent` | `int32` | The progress of the export, 0-100, or -1 when the export is not running. |
| `status_explanation` | `string` | A description of the current state; the error message if the export failed. |
## Response: UpdateExportedDataSetExecutionStatusResponse
No fields.
---
# Data export (IRPCDataExport)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/
Reads objects, value list items and property value history in bulk, in batches ordered by ID,
for exporting vault data to another system.
- **gRPC service:** `MFiles.IRPCDataExport`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 5
- **Proto file:** [`mfiles/IRPCDataExport.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCDataExport.proto)
## Overview
The methods are built for bulk reading with stable paging: each batch continues after the last
ID the caller received. M-Files Reporting uses them to fill reporting databases (see
[IRPCExportedDataSets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/index.md)), but they work for any session and
always apply the caller's permissions.
A typical export of one object type:
1. Page through the objects with
[SearchExportedObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/SearchExportedObjects/index.md): conditions that
select one object type, `last_received_obj_id` 0 first, then the ID of the last object
received, until a batch comes back empty.
2. Read the properties of each batch with
[GetExportedObjectProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedObjectProperties/index.md).
3. Optionally read how a property changed over time with
[GetPropertyValueHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetPropertyValueHistory/index.md).
4. Page through the value lists that the properties refer to with
[GetExportedValueListItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItems/index.md), or fetch
single items with
[GetExportedValueListItemsByID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItemsByID/index.md).
All methods need a vault session and no special vault rights; objects, values and items the
user cannot see are left out. For interactive searches use
[SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md) instead.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetExportedObjectProperties](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedObjectProperties/index.md) | Gets the version information and property values of many objects in one call. | `read` `session` `idempotent` |
| [GetExportedValueListItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItems/index.md) | Gets the items of a value list in batches ordered by item ID. | `read` `session` `idempotent` |
| [GetExportedValueListItemsByID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItemsByID/index.md) | Gets the given items of a value list. | `read` `session` `idempotent` |
| [GetPropertyValueHistory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetPropertyValueHistory/index.md) | Gets how one property of each given object changed over the object's versions. | `read` `session` `idempotent` |
| [SearchExportedObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/SearchExportedObjects/index.md) | Searches objects in batches ordered by object ID, for paging through all objects that match. | `read` `session` `idempotent` |
---
# IRPCDataExport.GetExportedObjectProperties
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedObjectProperties/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets the version information and property values of many objects in one call.
- **Service:** [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md) `MFiles.IRPCDataExport`
- **gRPC method:** `/MFiles.IRPCDataExport/GetExportedObjectProperties`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-object-properties`
- **Request:** [`GetExportedObjectPropertiesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedObjectProperties/index.md#request)
- **Response:** [`GetExportedObjectPropertiesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedObjectProperties/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- The response has one entry per requested object, in request order, in both
`object_version_ex` and `prop_val_arrays`.
- A version with `OBJ_VER_VERSION_TYPE_LATEST` reads the latest checked-in version.
- An object that does not exist, has no checked-in version, or that the user cannot see gets
an empty entry. For a destroyed object, only `object_version_ex.object_info.obj_id` is set,
so you can tell it apart from a hidden one; if Name or title (0) was requested its last name
is returned too.
- Each object may appear only once: a repeated object fails the call with "Already exists.".
## Request: GetExportedObjectPropertiesRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `exportedobjects[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The objects to read. Each object at most once. |
| `exportedobjects[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `exportedobjects[].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). |
| `exportedobjects[].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`. |
| `exportedobjects[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `exportedobjects[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `exportedobjects[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `exportedobjects[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `exportedobjects[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `property_defs[]` | repeated `int32` | The IDs of the property definitions to return. Empty returns all properties. |
## Response: GetExportedObjectPropertiesResponse
> Nested 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_version_ex[]` | repeated [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The version information of each object, in request order. Empty for objects that were not found or not visible. |
| `object_version_ex[].version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `object_version_ex[].version_info.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version number, as a specific version. |
| `object_version_ex[].version_info.display_version` | `string` | The version label to show, if it differs from the version number; empty otherwise. |
| `object_version_ex[].version_info.title` | `string` | The title (name) of the object in this version. |
| `object_version_ex[].version_info.is_single_file_object` | `bool` | True if the object is a single-file document, which has exactly one file. |
| `object_version_ex[].version_info.has_relationships_from_this` | `bool` | Note: this field is deprecated. True if relationships from this object version to one or more documents exist. |
| `object_version_ex[].version_info.has_relationships_to_this` | `bool` | Note: this field is deprecated. True if relationships from one or more documents to this object version exist. |
| `object_version_ex[].version_info.has_assignments` | `bool` | True if relationships from one or more assignments to this object version exist. |
| `object_version_ex[].version_info.last_modified_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the version was last modified, in UTC. |
| `object_version_ex[].version_info.files[]` | repeated [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`. |
| `object_version_ex[].version_info.object_version_flags` | [`OBJVERFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJVERFLAGS/index.md) | Bit flags that provide additional information on the object version. |
| `object_version_ex[].version_info.class_id` | `int32` | The class ID of the version. |
| `object_version_ex[].version_info.version_guid` | `string` | The GUID of this version. |
| `object_version_ex[].version_info.base_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`. |
| `object_version_ex[].version_info.primary_file` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | File ID of the primary file of a multi-file object, if the object is a multi-file object. |
| `object_version_ex[].object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `object_version_ex[].object_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object type and ID of the object. |
| `object_version_ex[].object_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this object'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). |
| `object_version_ex[].object_info.external_id` | `string` | The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID. |
| `object_version_ex[].object_info.checked_out_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version that is checked out. Version number 0 if the object is not checked out. |
| `object_version_ex[].object_info.checked_out_to_user_id` | `int32` | The ID of the user who has the object checked out. |
| `object_version_ex[].object_info.checked_out_to_user_name` | `string` | The user name of the user who has the object checked out. |
| `object_version_ex[].object_info.checked_out_to_host_name` | `string` | The host name of the computer to which the object was checked out. |
| `object_version_ex[].object_info.checked_out_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of the moment the object was checked out. |
| `object_version_ex[].object_info.checked_in_version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The latest checked-in version. |
| `object_version_ex[].object_info.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue). |
| `object_version_ex[].object_info.accessed_by_me_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back. |
| `object_version_ex[].object_info.guid` | `string` | The object GUID, in braces. The same value as `GetObjectGUID` returns. |
| `object_version_ex[].object_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 object (e.g. is the object deleted or a stub). |
| `object_version_ex[].object_info.original_vault_guid` | `string` | The GUID of the vault in which the object was originally created. |
| `object_version_ex[].object_info.original_vault_obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The original objid in the vault in which the object was originally created. |
| `object_version_ex[].object_info.associated_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | Identifies the view associated with this object if any. |
| `object_version_ex[].object_info.external_repository_icon_id` | `string` | If not null, identifies the icon of the object. Currently applicable only to unmanaged objects. |
| `object_version_ex[].object_info.primary_view_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects. |
| `object_version_ex[].object_info.capabilities` | [`OBJECTCAPABILITYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTCAPABILITYFLAGS/index.md) | Bit flags that provide information on the object capabilities. |
| `prop_val_arrays[]` | repeated [`PropertyValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValueArray/index.md) | The property values of each object, in request order. |
| `prop_val_arrays[].value[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Property values. |
| `prop_val_arrays[].value[].property_def` | `int32` | The property definition ID, for example 0 for "Name or title" or 100 for "Class". |
| `prop_val_arrays[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value. Its `type` must match the data type of the property definition. |
---
# IRPCDataExport.GetExportedValueListItems
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItems/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets the items of a value list in batches ordered by item ID.
- **Service:** [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md) `MFiles.IRPCDataExport`
- **gRPC method:** `/MFiles.IRPCDataExport/GetExportedValueListItems`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-value-list-items`
- **Request:** [`GetExportedValueListItemsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItems/index.md#request)
- **Response:** [`GetExportedValueListItemsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItems/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Returns items whose ID is greater than `last_received_item_id`, ascending by ID. Deleted items
are left out. Parents of matching items are not added.
- Works for value lists and object types. An unknown list fails with "Not found.".
- Stop when a batch is empty.
## Request: GetExportedValueListItemsRequest
> Nested 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 or object type. |
| `last_received_item_id` | `uint32` | The ID of the last item received in the previous batch; 0 for the first batch. |
| `batch_size` | `uint32` | The maximum number of items to return; 0 returns all. |
## Response: GetExportedValueListItemsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pexportedvlitems[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The items. See [ValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md). |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].item_info.name` | `string` | The name of the item. |
| `pexportedvlitems[].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). |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].item_info.guid` | `string` | GUID for the item. |
| `pexportedvlitems[].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). |
| `pexportedvlitems[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `pexportedvlitems[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `pexportedvlitems[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `pexportedvlitems[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `pexportedvlitems[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `pexportedvlitems[].owner_name` | `string` | The name of the owner item. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].icon.value` | `bytes` | Array of bytes. |
## Related methods
- [GetExportedValueListItemsByID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItemsByID/index.md): Gets the given items of a value list.
---
# IRPCDataExport.GetExportedValueListItemsByID
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItemsByID/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets the given items of a value list.
- **Service:** [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md) `MFiles.IRPCDataExport`
- **gRPC method:** `/MFiles.IRPCDataExport/GetExportedValueListItemsByID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-value-list-items-by-id`
- **Request:** [`GetExportedValueListItemsByIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItemsByID/index.md#request)
- **Response:** [`GetExportedValueListItemsByIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItemsByID/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- IDs that do not exist, and items the user cannot see, are left out of the response, so it
can be shorter than `ids`.
## Request: GetExportedValueListItemsByIDRequest
> Nested 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 or object type. |
| `ids[]` | repeated `int32` | The IDs of the items to get. |
## Response: GetExportedValueListItemsByIDResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pexportedvlitems[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The items found. See [ValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md). |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].item_info.name` | `string` | The name of the item. |
| `pexportedvlitems[].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). |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].item_info.guid` | `string` | GUID for the item. |
| `pexportedvlitems[].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). |
| `pexportedvlitems[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `pexportedvlitems[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `pexportedvlitems[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `pexportedvlitems[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `pexportedvlitems[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `pexportedvlitems[].owner_name` | `string` | The name of the owner item. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `pexportedvlitems[].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. |
| `pexportedvlitems[].icon.value` | `bytes` | Array of bytes. |
## Related methods
- [GetExportedValueListItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetExportedValueListItems/index.md): Gets the items of a value list in batches ordered by item ID.
---
# IRPCDataExport.GetPropertyValueHistory
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetPropertyValueHistory/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets how one property of each given object changed over the object's versions.
- **Service:** [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md) `MFiles.IRPCDataExport`
- **gRPC method:** `/MFiles.IRPCDataExport/GetPropertyValueHistory`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-property-value-history`
- **Request:** [`GetPropertyValueHistoryRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetPropertyValueHistory/index.md#request)
- **Response:** [`GetPropertyValueHistoryResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/GetPropertyValueHistory/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- The history of an object is a list of samples, oldest first. A new sample starts only when
the value changes, so unchanged versions do not repeat it. When the property was removed from
a version, the sample has an unset value.
- Each sample's `timestamp` is the Last modified (21) value of the version where the value
appeared.
- With `from` set, older samples are dropped, except the last one at or before `from`, so the
value in effect at `from` is known. Unset `from` returns the full history.
- The response has one entry per requested object, in request order; objects the user cannot
see get an empty history. Each object may appear only once ("Already exists." otherwise).
## Request: GetPropertyValueHistoryRequest
> Nested 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 whose history is wanted. |
| `obj_ids[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The objects. Each object at most once. |
| `obj_ids[].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_ids[].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_ids[].item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_ids[].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. |
| `from` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The oldest point in time of interest; unset for the full history. |
## Response: GetPropertyValueHistoryResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `historical_typed_value_arrays[]` | repeated [`HistoricalTypedValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.HistoricalTypedValueArray/index.md) | One history per requested object, in request order. See [HistoricalTypedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.HistoricalTypedValue/index.md). |
| `historical_typed_value_arrays[].value[]` | repeated [`HistoricalTypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.HistoricalTypedValue/index.md) | Items. |
| `historical_typed_value_arrays[].value[].timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Historical value's timestamp. |
| `historical_typed_value_arrays[].value[].version` | `int32` | Object's version from which the value has been originated. |
| `historical_typed_value_arrays[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The historical value. |
---
# IRPCDataExport.SearchExportedObjects
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/SearchExportedObjects/
Badges: `Vault API / standard` `read` `session` `idempotent`
Searches objects in batches ordered by object ID, for paging through all objects that match.
- **Service:** [Data export](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/index.md) `MFiles.IRPCDataExport`
- **gRPC method:** `/MFiles.IRPCDataExport/SearchExportedObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-exported-objects`
- **Request:** [`SearchExportedObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/SearchExportedObjects/index.md#request)
- **Response:** [`SearchExportedObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDataExport/SearchExportedObjects/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Returns the latest checked-in version of each matching object, ordered by object ID. Objects
that have only an initial checked-out version are not returned.
- The server adds the condition "object ID greater than `last_received_obj_id`" to your
conditions. Paging is by object ID only, and IDs repeat across object types, so **include a
condition on one object type** (`STATUS_TYPE_OBJECT_TYPE`) when you page; without it, objects
of other types with smaller IDs are skipped or repeated.
- Stop when a batch is empty. Results are not ranked by relevance.
## Request: SearchExportedObjectsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `condition_array[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | Search conditions, combined with AND. See [SearchCondition](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) and [Search](https://developer.m-files.com/APIs/gRPC-API/concepts/search/index.md). |
| `condition_array[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `condition_array[].expression.type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `condition_array[].expression.data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `condition_array[].expression.indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `condition_array[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `condition_array[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `condition_array[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `condition_array[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `condition_array[].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_received_obj_id` | `uint32` | The ID of the last object received in the previous batch; 0 for the first batch. |
| `batch_size` | `uint32` | The maximum number of objects to return; 0 returns all matching objects. |
## Response: SearchExportedObjectsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `pexportedobjects[]` | repeated [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The matching objects as [ObjVer](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md)s with a specific version (the latest checked-in version), in ascending object ID order. |
| `pexportedobjects[].obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `pexportedobjects[].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). |
| `pexportedobjects[].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`. |
| `pexportedobjects[].version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `pexportedobjects[].version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `pexportedobjects[].version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `pexportedobjects[].version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `pexportedobjects[].version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
---
# Scanning and OCR (IRPCScanningAndOCR)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/
Runs server-side OCR: converts files to searchable PDF and recognizes text in page areas.
- **gRPC service:** `MFiles.IRPCScanningAndOCR`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 8
- **Proto file:** [`mfiles/IRPCScanningAndOCR.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCScanningAndOCR.proto)
## Overview
OCR runs on the server as a background operation of the calling session. A job is started,
polled and ended:
1. Check that server OCR is available with
[GetScanningAndOCROptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetScanningAndOCROptions/index.md)
(`allow_server_ocr`, `allowed_file_extensions`).
2. Start the job:
- on a file you upload:
[OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md),
or
- on a file of a checked-out document in the vault:
[OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md).
3. Poll [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md) until `done`.
4. End the job, which also releases it:
- [OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md)
returns the recognized texts and a download of the resulting PDF, or
- [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md) replaces the
document's file in the vault with the resulting PDF.
The `background_op_id` exists only in the memory of the server that started the job: poll and
end the job on the same server. After the job has ended, or after
it failed and the failure was reported, the ID is no longer valid and calls fail with "The
parameter is incorrect.".
**Operation types** ([OCROperationType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCROperationType/index.md)):
`..._CONVERT_TO_SEARCHABLE_PDF` and `..._CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` (PDF/A-1b) produce a
PDF; `..._RECOGNIZE_SPECIFIC_BLOCKS` reads the text of the areas given in `pages`; `..._RECOGNIZE_ANY_BLOCKS` returns the text areas it
finds; the combined types do both.
All methods need a vault session. Files are covered in
[Files](https://developer.m-files.com/APIs/gRPC-API/runtime/files/index.md).
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetOCRUploadedFileStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/index.md) | Gets the state of an OCR job started with OCRUploadedFile and, when it has completed, its result as a `file_ref`. Optionally requests the cancellation of the job. | `write` `session` |
| [GetScanningAndOCROptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetScanningAndOCROptions/index.md) | Gets whether scanning and client- and server-side OCR are enabled for the vault, and for which file types. | `read` `session` `idempotent` `returns metadata structure version` |
| [OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md) | Starts an OCR job on a file of a document that the caller has checked out. | `write` `session` `idempotent` `returns metadata structure version` |
| [OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md) | Starts an OCR job on a file that the caller uploaded with UploadTempFile. | `write` `session` `idempotent` `returns metadata structure version` |
| [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md) | Ends an OCR job started with OCROperation_Begin and replaces the document's file with the resulting PDF. | `write` `session` `returns metadata structure version` |
| [OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md) | Ends an OCR job and returns its results: the recognized texts and a download of the PDF. | `write` `session` `returns metadata structure version` |
| [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md) | Gets the progress of an OCR job, and optionally cancels it. | `write` `session` `idempotent` `returns metadata structure version` |
| [OCRUploadedFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCRUploadedFile/index.md) | Starts an OCR job that converts the file of a stateless upload to a searchable PDF. | `write` `session` |
---
# IRPCScanningAndOCR.GetOCRUploadedFileStatus
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/
Badges: `Vault API / standard` `write` `session`
Gets the state of an OCR job started with OCRUploadedFile and, when it has completed, its
result as a `file_ref`. Optionally requests the cancellation of the job.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-ocruploaded-file-status`
- **Request:** [`GetOCRUploadedFileStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/index.md#request)
- **Response:** [`GetOCRUploadedFileStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Not available on current servers: the call fails with "Not implemented.".
- The job belongs to the login session that started it; other sessions get "The OCR job was not
found in this session.". Once a completed, failed or canceled state has been returned, the
job is released.
## Request: GetOCRUploadedFileStatusRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `job_id` | `string` | The ID of the job from [OCRUploadedFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCRUploadedFile/index.md). |
| `cancel` | `bool` | True to request the cancellation of the job. The returned state can still be queued or running until the job has stopped. |
## Response: GetOCRUploadedFileStatusResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `state` | [`OCRUploadedFileState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRUploadedFileState/index.md) | The state of the job. Values: `OCRUPLOADED_FILE_STATE_UNSPECIFIED` (0), `OCRUPLOADED_FILE_STATE_QUEUED` (1), `OCRUPLOADED_FILE_STATE_RUNNING` (2), `OCRUPLOADED_FILE_STATE_COMPLETED` (3), `OCRUPLOADED_FILE_STATE_FAILED` (4), `OCRUPLOADED_FILE_STATE_CANCELED` (5). |
| `pages_total` | `uint32` | The number of pages to process. Zero if not known yet. |
| `pages_completed` | `uint32` | The number of pages processed. |
| `result_file_ref` | `string` | If the state is completed, the file_ref of the searchable PDF, as a stateless upload that can be attached like an upload ended with FileUploadEnd. Otherwise empty. |
| `result_file_size` | `int64` | If the state is completed, the size of the searchable PDF in bytes. Otherwise zero. |
| `error_code` | `int32` | If the state is failed, the M-Files error code of the job; otherwise 0. |
| `error_message` | `string` | If the state is failed, the error message of the job. Otherwise empty. |
---
# IRPCScanningAndOCR.GetScanningAndOCROptions
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetScanningAndOCROptions/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Gets whether scanning and client- and server-side OCR are enabled for the vault, and for
which file types.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/GetScanningAndOCROptions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-scanning-and-ocroptions`
- **Request:** [`GetScanningAndOCROptionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetScanningAndOCROptions/index.md#request)
- **Response:** [`GetScanningAndOCROptionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetScanningAndOCROptions/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session; no special vault rights.
- `allow_server_ocr` is true only when server OCR is enabled in the vault settings, the license
includes OCR and the OCR engine could be started; otherwise the Begin methods fail with "OCR
feature is disabled by license or settings.". `ocr_setup_error_code` is non-zero when the
engine could not be started.
- `allowed_file_extensions` defaults to TIF, TIFF, JPG, JPEG and PDF.
## Request: GetScanningAndOCROptionsRequest
No fields.
## Response: GetScanningAndOCROptionsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `putf8szscanocrops` | [`ScanningAndOCROptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScanningAndOCROptions/index.md) | The scanning and OCR options of the vault. See [ScanningAndOCROptions](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScanningAndOCROptions/index.md). |
| `putf8szscanocrops.allow_scanning_from_clients` | `bool` | True if the whole client-side scanning feature is on. |
| `putf8szscanocrops.allow_client_ocr` | `bool` | True if the OCR feature is on for the client-side. |
| `putf8szscanocrops.allow_server_ocr` | `bool` | True if the OCR feature is on for the server-side. |
| `putf8szscanocrops.allowed_file_extensions[]` | repeated `string` | An array of file extensions (not including dot) for which scanning and OCR generation is allowed. |
| `putf8szscanocrops.ocr_setup_error_code` | `uint32` | OCR setup error code. |
| `putf8szscanocrops.ocr_options` | [`OCROptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCROptions/index.md) | Default options for OCR. |
| `putf8szscanocrops.ocr_options.languages[]` | repeated [`OCRLanguageType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRLanguageType/index.md) | Languages/character sets/dictionaries to be used as recognition hints. Can be unset. |
| `putf8szscanocrops.ocr_options.ocr_automatic_language_detection` | `bool` | True if the OCR automatic language detection is to be used. |
---
# IRPCScanningAndOCR.OCROperation_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Starts an OCR job on a file of a document that the caller has checked out.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/OCROperation_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/ocroperation_-begin`
- **Request:** [`OCROperation_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md#request)
- **Response:** [`OCROperation_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- The document must be checked out to the caller, and the caller needs read and edit access to
it. The initial checked-out version of a new document (version 1) is rejected: it has no
checked-in version.
- Nothing is uploaded: the content is read from the file in the latest checked-in version of
the document.
- Finish with [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md) to replace
the file in the checked-out version with the PDF, then check the document in.
## Request: OCROperation_BeginRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `type` | [`OCROperationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCROperationType/index.md) | What to produce. See the service overview. Values: `OCROPERATION_TYPE_NONE` (0), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` (1), `OCROPERATION_TYPE_RECOGNIZE_SPECIFIC_BLOCKS` (2), `OCROPERATION_TYPE_RECOGNIZE_ANY_BLOCKS` (3), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF_AND_RECOGNIZE_SPECIFIC_BLOCKS` (4), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF_AND_RECOGNIZE_ANY_BLOCKS` (5), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` (6), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF_AND_RECOGNIZE_SPECIFIC_BLOCKS` (7), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF_AND_RECOGNIZE_ANY_BLOCKS` (8). |
| `options` | [`OCROptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCROptions/index.md) | Recognition languages and automatic language detection. Unset uses the defaults. |
| `options.languages[]` | repeated [`OCRLanguageType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRLanguageType/index.md) | Languages/character sets/dictionaries to be used as recognition hints. Can be unset. |
| `options.ocr_automatic_language_detection` | `bool` | True if the OCR automatic language detection is to be used. |
| `obj_or_file_ver` | [`ObjOrFileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjOrFileVer/index.md) | The checked-out version (`obj_ver`) and the file (`file_ver`) to process. |
| `obj_or_file_ver.obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | Object version. The version part can be -1 to indicate the latest version. |
| `obj_or_file_ver.obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_or_file_ver.obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_or_file_ver.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | File version. Valid only if bIsFile is true. |
| `obj_or_file_ver.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `obj_or_file_ver.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `obj_or_file_ver.file_ver.internal_version` | `int32` | The file version number. |
| `obj_or_file_ver.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `obj_or_file_ver.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `source_file_extension` | `string` | The file name extension, without the dot. |
| `pages` | [`OCRPageArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRPageArray/index.md) | For `..._RECOGNIZE_SPECIFIC_BLOCKS` types, the areas to recognize. Otherwise unset. |
| `pages.value[]` | repeated [`OCRPage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRPage/index.md) | An array of OCR pages, should be ordered by the page number. |
| `pages.value[].number` | `uint32` | Page number of this page. |
| `pages.value[].blocks[]` | repeated [`OCRBlock`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRBlock/index.md) | An array of OCR blocks. |
## Response: OCROperation_BeginResponse
> Nested 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` | `uint32` | The ID of the job. |
## Related methods
- [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md): Ends an OCR job started with OCROperation_Begin and replaces the document's file with the resulting PDF.
- [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md): Gets the progress of an OCR job, and optionally cancels it.
- [OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md): Starts an OCR job on a file that the caller uploaded with UploadTempFile.
- [OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md): Ends an OCR job and returns its results: the recognized texts and a download of the PDF.
---
# IRPCScanningAndOCR.OCROperation_BeginAfterUpload
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Starts an OCR job on a file that the caller uploaded with UploadTempFile.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/ocroperation_-begin-after-upload`
- **Request:** [`OCROperation_BeginAfterUploadRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md#request)
- **Response:** [`OCROperation_BeginAfterUploadResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Upload the file with [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md) and
pass its `upload_id` and size here. **Do not commit the upload** with
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): this call
commits it itself, and an upload that is already committed fails with "File size mismatch.".
- The upload is consumed, also when the call fails.
- Fails with "OCR feature is disabled by license or settings." when server OCR is not
available.
- Returns at once; poll [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md)
and finish with
[OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md).
## Request: OCROperation_BeginAfterUploadRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `type` | [`OCROperationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCROperationType/index.md) | What to produce. See the service overview. Values: `OCROPERATION_TYPE_NONE` (0), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` (1), `OCROPERATION_TYPE_RECOGNIZE_SPECIFIC_BLOCKS` (2), `OCROPERATION_TYPE_RECOGNIZE_ANY_BLOCKS` (3), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF_AND_RECOGNIZE_SPECIFIC_BLOCKS` (4), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF_AND_RECOGNIZE_ANY_BLOCKS` (5), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` (6), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF_AND_RECOGNIZE_SPECIFIC_BLOCKS` (7), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF_AND_RECOGNIZE_ANY_BLOCKS` (8). |
| `options` | [`OCROptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCROptions/index.md) | Recognition languages and automatic language detection. Unset uses the defaults. |
| `options.languages[]` | repeated [`OCRLanguageType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRLanguageType/index.md) | Languages/character sets/dictionaries to be used as recognition hints. Can be unset. |
| `options.ocr_automatic_language_detection` | `bool` | True if the OCR automatic language detection is to be used. |
| `upload_session` | `int32` | The `upload_id` of an uploaded, not committed file. |
| `upload_file_size` | `int64` | The size of the uploaded file in bytes; must match the uploaded bytes. |
| `source_file_extension` | `string` | The file name extension of the uploaded file, without the dot, for example `pdf` or `tif`. |
| `pages` | [`OCRPageArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRPageArray/index.md) | For `..._RECOGNIZE_SPECIFIC_BLOCKS` types, the areas to recognize, per page. Otherwise leave unset. |
| `pages.value[]` | repeated [`OCRPage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRPage/index.md) | An array of OCR pages, should be ordered by the page number. |
| `pages.value[].number` | `uint32` | Page number of this page. |
| `pages.value[].blocks[]` | repeated [`OCRBlock`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRBlock/index.md) | An array of OCR blocks. |
## Response: OCROperation_BeginAfterUploadResponse
> Nested 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` | `uint32` | The ID of the job. |
## Related methods
- [IRPCObjectOperations.UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
- [IRPCObjectOperations.UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.
- [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md): Gets the progress of an OCR job, and optionally cancels it.
- [OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md): Ends an OCR job and returns its results: the recognized texts and a download of the PDF.
- [OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md): Starts an OCR job on a file of a document that the caller has checked out.
- [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md): Ends an OCR job started with OCROperation_Begin and replaces the document's file with the resulting PDF.
---
# IRPCScanningAndOCR.OCROperation_End
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Ends an OCR job started with OCROperation_Begin and replaces the document's file with the
resulting PDF.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/OCROperation_End`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/ocroperation_-end`
- **Request:** [`OCROperation_EndRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md#request)
- **Response:** [`OCROperation_EndResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Only for jobs started with
[OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md); other jobs fail
with "OCR processing has not been started.".
- For the types that produce a PDF, the file in the checked-out version is replaced with the
PDF and its extension changes to `pdf`. Check the document in to save the change.
- The job is released; the ID cannot be used again. If the job failed, the call fails with the
job's error.
## Request: OCROperation_EndRequest
> Nested 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` | `uint32` | The ID of the job. |
## Response: OCROperation_EndResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `page_results[]` | repeated [`OCRPageResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRPageResult/index.md) | The recognized areas and their texts, per page. Empty if the type did not recognize areas. |
| `page_results[].number` | `uint32` | Page number of this page. |
| `page_results[].blocks[]` | repeated [`OCRBlockResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRBlockResult/index.md) | An array of OCR block results. |
| `page_results[].blocks[].id` | `int32` | Id of the OCR block. Negative value if there was no request block. |
| `page_results[].blocks[].dimension_unit` | [`OCRBlockDimUnitType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRBlockDimUnitType/index.md) | Defines the unit of the block rectangle dimensions. Default is pixels. Values: `OCRBLOCK_DIM_UNIT_TYPE_PIXELS` (0), `OCRBLOCK_DIM_UNIT_TYPE_MILLIMETERS_X10` (1), `OCRBLOCK_DIM_UNIT_TYPE_INCHES_X100` (2). |
| `page_results[].blocks[].left` | `uint32` | Distance from the left of the image. |
| `page_results[].blocks[].top` | `uint32` | Distance from the top of the image. |
| `page_results[].blocks[].width` | `uint32` | Width of the block rectangle. |
| `page_results[].blocks[].height` | `uint32` | Height of the block rectangle. |
| `page_results[].blocks[].confidence` | `int32` | Confidence level (0 = most confident, 255 = least confident). |
| `page_results[].blocks[].page` | `uint32` | One-based number of the page on which this result was recognized. 0 means no recognition. |
| `page_results[].blocks[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The recognized value. |
## Related methods
- [OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md): Starts an OCR job on a file of a document that the caller has checked out.
- [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md): Gets the progress of an OCR job, and optionally cancels it.
- [OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md): Starts an OCR job on a file that the caller uploaded with UploadTempFile.
- [OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md): Ends an OCR job and returns its results: the recognized texts and a download of the PDF.
---
# IRPCScanningAndOCR.OCROperation_EndWithDownload
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Ends an OCR job and returns its results: the recognized texts and a download of the PDF.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/ocroperation_-end-with-download`
- **Request:** [`OCROperation_EndWithDownloadRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md#request)
- **Response:** [`OCROperation_EndWithDownloadResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Call after [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md)
reports `done`. The job is released; the ID cannot be used again.
- For the types that produce a PDF, read the file with
[DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md) using
`download_session`, and release the download with
[DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md). For the
recognize-only types `download_file_size` is 0.
- If the job failed, the call fails with the job's error.
## Request: OCROperation_EndWithDownloadRequest
> Nested 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` | `uint32` | The ID of the job. |
## Response: OCROperation_EndWithDownloadResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `page_results[]` | repeated [`OCRPageResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRPageResult/index.md) | The recognized areas and their texts, per page. Empty for the types that only produce a PDF. |
| `page_results[].number` | `uint32` | Page number of this page. |
| `page_results[].blocks[]` | repeated [`OCRBlockResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCRBlockResult/index.md) | An array of OCR block results. |
| `page_results[].blocks[].id` | `int32` | Id of the OCR block. Negative value if there was no request block. |
| `page_results[].blocks[].dimension_unit` | [`OCRBlockDimUnitType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRBlockDimUnitType/index.md) | Defines the unit of the block rectangle dimensions. Default is pixels. Values: `OCRBLOCK_DIM_UNIT_TYPE_PIXELS` (0), `OCRBLOCK_DIM_UNIT_TYPE_MILLIMETERS_X10` (1), `OCRBLOCK_DIM_UNIT_TYPE_INCHES_X100` (2). |
| `page_results[].blocks[].left` | `uint32` | Distance from the left of the image. |
| `page_results[].blocks[].top` | `uint32` | Distance from the top of the image. |
| `page_results[].blocks[].width` | `uint32` | Width of the block rectangle. |
| `page_results[].blocks[].height` | `uint32` | Height of the block rectangle. |
| `page_results[].blocks[].confidence` | `int32` | Confidence level (0 = most confident, 255 = least confident). |
| `page_results[].blocks[].page` | `uint32` | One-based number of the page on which this result was recognized. 0 means no recognition. |
| `page_results[].blocks[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The recognized value. |
| `download_session` | `int32` | The download ID of the resulting PDF. |
| `download_file_size` | `int64` | The size of the resulting PDF in bytes; 0 if none. |
## Related methods
- [OCROperation_Status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md): Gets the progress of an OCR job, and optionally cancels it.
- [IRPCObjectOperations.DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md): Reads a block of a file from a download session.
- [IRPCObjectOperations.DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md): Closes a download session.
- [OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md): Starts an OCR job on a file that the caller uploaded with UploadTempFile.
- [OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md): Starts an OCR job on a file of a document that the caller has checked out.
- [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md): Ends an OCR job started with OCROperation_Begin and replaces the document's file with the resulting PDF.
---
# IRPCScanningAndOCR.OCROperation_Status
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Gets the progress of an OCR job, and optionally cancels it.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/OCROperation_Status`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/ocroperation_-status`
- **Request:** [`OCROperation_StatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md#request)
- **Response:** [`OCROperation_StatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Status/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Poll until `done` is true, then end the job.
- If the job failed, the call fails with the job's error and the job is released.
- An unknown or already ended job fails with "The parameter is incorrect.".
## Request: OCROperation_StatusRequest
> Nested 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` | `uint32` | The ID of the job. |
| `cancel` | `bool` | True to cancel the job. |
## Response: OCROperation_StatusResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `items` | `uint32` | The number of pages to process; 0 until known. |
| `items_completed` | `uint32` | The number of pages processed. |
| `done` | `bool` | True when the job has stopped. |
## Related methods
- [OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md): Starts an OCR job on a file that the caller uploaded with UploadTempFile.
- [OCROperation_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_Begin/index.md): Starts an OCR job on a file of a document that the caller has checked out.
- [OCROperation_End](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_End/index.md): Ends an OCR job started with OCROperation_Begin and replaces the document's file with the resulting PDF.
- [OCROperation_EndWithDownload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_EndWithDownload/index.md): Ends an OCR job and returns its results: the recognized texts and a download of the PDF.
---
# IRPCScanningAndOCR.OCRUploadedFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCRUploadedFile/
Badges: `Vault API / standard` `write` `session`
Starts an OCR job that converts the file of a stateless upload to a searchable PDF.
- **Service:** [Scanning and OCR](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/index.md) `MFiles.IRPCScanningAndOCR`
- **gRPC method:** `/MFiles.IRPCScanningAndOCR/OCRUploadedFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/ocruploaded-file`
- **Request:** [`OCRUploadedFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCRUploadedFile/index.md#request)
- **Response:** [`OCRUploadedFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCRUploadedFile/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Not available on current servers: the call fails with "Not implemented.". Use
[OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md)
instead.
- Takes the `file_ref` of an upload ended with
[FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md). Only
`OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` and
`OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` are accepted.
- Follow the job with
[GetOCRUploadedFileStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/index.md).
## Request: OCRUploadedFileRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_ref` | `string` | The file_ref of a stateless upload ended with FileUploadEnd, to be used as input for the OCR job. |
| `source_file_extension` | `string` | The filename extension (without dot) of the source file. Required, as a file_ref has no file name. |
| `type` | [`OCROperationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCROperationType/index.md) | `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` or `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF`; other types fail. Values: `OCROPERATION_TYPE_NONE` (0), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` (1), `OCROPERATION_TYPE_RECOGNIZE_SPECIFIC_BLOCKS` (2), `OCROPERATION_TYPE_RECOGNIZE_ANY_BLOCKS` (3), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF_AND_RECOGNIZE_SPECIFIC_BLOCKS` (4), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF_AND_RECOGNIZE_ANY_BLOCKS` (5), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` (6), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF_AND_RECOGNIZE_SPECIFIC_BLOCKS` (7), `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF_AND_RECOGNIZE_ANY_BLOCKS` (8). |
| `options` | [`OCROptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OCROptions/index.md) | OCR options to be used for this job. If unset, default settings are used. |
| `options.languages[]` | repeated [`OCRLanguageType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.OCRLanguageType/index.md) | Languages/character sets/dictionaries to be used as recognition hints. Can be unset. |
| `options.ocr_automatic_language_detection` | `bool` | True if the OCR automatic language detection is to be used. |
## Response: OCRUploadedFileResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `job_id` | `string` | The ID of the job, for [GetOCRUploadedFileStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/index.md). |
## Related methods
- [OCROperation_BeginAfterUpload](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/OCROperation_BeginAfterUpload/index.md): Starts an OCR job on a file that the caller uploaded with UploadTempFile.
- [IRPCFileTransfer.FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md): Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or AddObjectWithFiles for that.
- [GetOCRUploadedFileStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScanningAndOCR/GetOCRUploadedFileStatus/index.md): Gets the state of an OCR job started with OCRUploadedFile and, when it has completed, its result as a `file_ref`. Optionally requests the cancellation of the job.
---
# Vault extension methods (IRPCVaultExtensionMethods)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/
Calls vault extension methods: server-side code in the vault that takes a string and returns a
string.
- **gRPC service:** `MFiles.IRPCVaultExtensionMethods`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 5
- **Proto file:** [`mfiles/IRPCVaultExtensionMethods.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaultExtensionMethods.proto)
## Overview
A vault extension method is custom server code that a client calls by name. There are two kinds:
- **Event handler methods**: event handlers of the type VaultExtensionMethod, written in
VBScript in M-Files Admin or registered by a vault application. They are identified by name
only. Call them with [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md)
with an all-zero `application_id`, or with
[ExecuteExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod/index.md).
- **Application extension methods**: methods of an extension object of a vault application,
identified by the application GUID, the extension, the instance and the method name. Call
them with [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md) or
[ExecuteExtensionMethodEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx/index.md).
Prefer [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md): it
covers both kinds and can compress large inputs and outputs. The input and output are free-form
strings; their format is defined by the method. Each call runs in its own
transaction.
[ExecuteAnonymousExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteAnonymousExtensionMethod/index.md)
is for the web server that passes anonymous HTTP requests (webhooks) to a vault application.
Errors: an unknown event handler method fails with "Not found. ()"; an unknown application
extension fails with `The specified application "" does not exist.`.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [ExecuteAnonymousExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteAnonymousExtensionMethod/index.md) | Passes an anonymous HTTP request, such as a webhook call, to a vault application. Used by the M-Files web server. | `write` `no session` `returns metadata structure version` |
| [ExecuteExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod/index.md) | Runs an event handler method by name. In new code use RunExtensionMethod. | `write` `session` `idempotent` `returns metadata structure version` |
| [ExecuteExtensionMethodEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx/index.md) | Runs an extension method of a vault application. In new code use RunExtensionMethod. | `write` `session` `returns metadata structure version` |
| [IsExtensionMethodAvailable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/IsExtensionMethodAvailable/index.md) | Tells whether an event handler method with the given name exists and is active. | `read` `session` `idempotent` `returns metadata structure version` |
| [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md) | Runs a vault extension method, either an event handler method or an application extension method, with optional compression of the input and output. | `write` `session` `returns metadata structure version` |
---
# IRPCVaultExtensionMethods.ExecuteAnonymousExtensionMethod
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteAnonymousExtensionMethod/
Badges: `Vault API / standard` `write` `no session` `returns metadata structure version`
Passes an anonymous HTTP request, such as a webhook call, to a vault application. Used by the
M-Files web server.
- **Service:** [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md) `MFiles.IRPCVaultExtensionMethods`
- **gRPC method:** `/MFiles.IRPCVaultExtensionMethods/ExecuteAnonymousExtensionMethod`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/execute-anonymous-extension-method`
- **Request:** [`ExecuteAnonymousExtensionMethodRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteAnonymousExtensionMethod/index.md#request)
- **Response:** [`ExecuteAnonymousExtensionMethodResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteAnonymousExtensionMethod/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- No session is needed. The server finds the vault by `vault_dns`, which must match a host name
that the server administrator has mapped to a vault; otherwise the call fails with "The
parameter is incorrect.".
- The method runs without a user. The receiving application must authenticate and validate the
request itself.
- `http_path` must not be empty and is limited to 10240 characters. `http_method` must be one of
CONNECT, DELETE, GET, HEAD, OPTIONS, POST or PUT. Other values fail with "The parameter is
incorrect.".
## Request: ExecuteAnonymousExtensionMethodRequest
> Nested 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` | `string` | The host name of the vault, as mapped on the server. |
| `method_identifier` | `string` | The name of the anonymous extension method. |
| `http_path` | `string` | The path and query string of the HTTP request. |
| `http_method` | `string` | The HTTP method of the request, for example `POST`. |
| `http_headers[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | The headers of the HTTP request. |
| `http_headers[].key` | `string` | The name of the value. |
| `http_headers[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `http_headers[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `http_headers[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `http_headers[].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. |
| `request_body` | `bytes` | The body of the HTTP request. |
## Response: ExecuteAnonymousExtensionMethodResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `response_http_headers[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | The headers to return in the HTTP response. |
| `response_http_headers[].key` | `string` | The name of the value. |
| `response_http_headers[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
| `response_http_headers[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `response_http_headers[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `response_http_headers[].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. |
| `response_body` | `bytes` | The body of the HTTP response. |
---
# IRPCVaultExtensionMethods.ExecuteExtensionMethod
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Runs an event handler method by name. In new code use RunExtensionMethod.
- **Service:** [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md) `MFiles.IRPCVaultExtensionMethods`
- **gRPC method:** `/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/execute-extension-method`
- **Request:** [`ExecuteExtensionMethodRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod/index.md#request)
- **Response:** [`ExecuteExtensionMethodResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Same as [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md) with
an all-zero `application_id` and uncompressed input.
- An unknown name fails with "Not found. ()".
## Request: ExecuteExtensionMethodRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_identifier` | `string` | The name of the VaultExtensionMethod event handler. |
| `input` | `string` | The input passed to the method. |
## Response: ExecuteExtensionMethodResponse
> Nested 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` | `string` | The output of the method. |
## Related methods
- [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md): Runs a vault extension method, either an event handler method or an application extension method, with optional compression of the input and output.
- [ExecuteExtensionMethodEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx/index.md): Runs an extension method of a vault application. In new code use RunExtensionMethod.
---
# IRPCVaultExtensionMethods.ExecuteExtensionMethodEx
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Runs an extension method of a vault application. In new code use RunExtensionMethod.
- **Service:** [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md) `MFiles.IRPCVaultExtensionMethods`
- **gRPC method:** `/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/execute-extension-method-ex`
- **Request:** [`ExecuteExtensionMethodExRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx/index.md#request)
- **Response:** [`ExecuteExtensionMethodExResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethodEx/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Same as [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md) with
an application GUID and uncompressed input.
- `application`, `extension` and `method` are required; an empty or all-zero `application`
fails with "The parameter is incorrect.".
## Request: ExecuteExtensionMethodExRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `application` | `string` | The GUID of the vault application. |
| `extension` | `string` | The identifier of the application's extension object. |
| `instance` | `string` | The identifier of the extension object instance. |
| `method` | `string` | The name of the method. |
| `input` | `string` | The input passed to the method. |
## Response: ExecuteExtensionMethodExResponse
> Nested 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` | `string` | The output of the method. |
## Related methods
- [RunExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md): Runs a vault extension method, either an event handler method or an application extension method, with optional compression of the input and output.
- [ExecuteExtensionMethod](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/ExecuteExtensionMethod/index.md): Runs an event handler method by name. In new code use RunExtensionMethod.
---
# IRPCVaultExtensionMethods.IsExtensionMethodAvailable
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/IsExtensionMethodAvailable/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Tells whether an event handler method with the given name exists and is active.
- **Service:** [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md) `MFiles.IRPCVaultExtensionMethods`
- **gRPC method:** `/MFiles.IRPCVaultExtensionMethods/IsExtensionMethodAvailable`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-extension-method-available`
- **Request:** [`IsExtensionMethodAvailableRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/IsExtensionMethodAvailable/index.md#request)
- **Response:** [`IsExtensionMethodAvailableResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/IsExtensionMethodAvailable/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Checks only the VaultExtensionMethod event handlers of the vault. Application extension
methods and the server's built-in methods are not reported.
- A name that does not exist returns `exists` false; the call does not fail.
## Request: IsExtensionMethodAvailableRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `method_identifier` | `string` | The name of the VaultExtensionMethod event handler. |
## Response: IsExtensionMethodAvailableResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `exists` | `bool` | True if an event handler with the name exists. |
| `is_active` | `bool` | True if that event handler is active. |
---
# IRPCVaultExtensionMethods.RunExtensionMethod
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Runs a vault extension method, either an event handler method or an application extension
method, with optional compression of the input and output.
- **Service:** [Vault extension methods](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/index.md) `MFiles.IRPCVaultExtensionMethods`
- **gRPC method:** `/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/run-extension-method`
- **Request:** [`RunExtensionMethodRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md#request)
- **Response:** [`RunExtensionMethodResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultExtensionMethods/RunExtensionMethod/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session; no special vault rights. The method's own code decides what the
caller may do.
- With an all-zero (or empty) `application_id`, `method_name` names an event handler method and
`extension` and `instance` are ignored. Otherwise the call goes to the extension object of the
application.
- **Compression.** Set either `input` or `compressed_input`. When `compressed_input` is set, the
server returns the output in `compressed_output` and leaves `output` empty. The compressed
format is not plain zlib: it is a 4-byte little-endian length of the uncompressed data,
followed by the zlib stream (RFC 1950) of the UTF-8 text **with a terminating zero byte**; the
length includes that byte. Data in another format fails with "The parameter is incorrect.".
The uncompressed size is limited to 100 MiB.
## Request: RunExtensionMethodRequest
Request data for running an extension 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 |
|---|---|---|
| `application_id` | `string` | The GUID of the vault application. All zeros or empty for an event handler method. |
| `extension` | `string` | The identifier of the application's extension object; empty for an event handler method. |
| `instance` | `string` | The identifier of the extension object instance; empty for an event handler method. |
| `method_name` | `string` | The name of the method. For an event handler method, the name of the VaultExtensionMethod event handler. |
| `input` | `string` | The input as text. Leave empty when `compressed_input` is used. |
| `compressed_input` | `bytes` | The compressed input: the 4-byte little-endian length of the UTF-8 text including a terminating zero byte, followed by the zlib stream of that text. Leave empty to use `input`. |
## Response: RunExtensionMethodResponse
The request data for RunExtensionMethod 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 |
|---|---|---|
| `output` | `string` | The output as text, when the input was not compressed. |
| `compressed_output` | `bytes` | When `compressed_input` was used, the output in the same compressed format: a 4-byte little-endian length, then the zlib stream of the UTF-8 text with a terminating zero byte. |
---
# Client scripts and UI extension applications (IRPCClientScript)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/
Lists, installs, enables, disables, licenses and removes the applications of the vault: vault
applications (server side) and UI extension applications (client side), and downloads their
packages and files.
- **gRPC service:** `MFiles.IRPCClientScript`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 16
- **Proto file:** [`mfiles/IRPCClientScript.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCClientScript.proto)
## Overview
An application is a ZIP package with an application definition (`appdef.xml`). Its GUID
identifies it in every call. [ExtApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplication/index.md) describes it;
`type` tells a vault application (`EXT_APPLICATION_TYPE_SERVER`) from a UI extension application
(`EXT_APPLICATION_TYPE_CLIENT`), and `platforms` (a bit mask of
[ExtApplicationPlatform](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationPlatform/index.md) values) the clients it supports.
**Reading:**
- [GetScriptApplicationsEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationsEx/index.md) lists the
applications; [GetScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplication/index.md)
gets one.
- [GetClientScriptApplicationsDetails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetClientScriptApplicationsDetails/index.md)
lists the modules and dashboards of the UI extension applications of the new M-Files clients.
- [DownloadScriptApplicationFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md)
and [DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md)
download an application package;
[GetDownloadSessionIdOfScriptApplicationFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md)
downloads one file of a UI extension application.
**Managing** (requires the vault right `change_metadata_structure`, see
[VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md); these are the operations of M-Files Admin):
- Install or upgrade: upload the package with
[UploadScriptApplicationFileBlockEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/index.md).
- Enable or disable a vault application:
[GetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/index.md),
[SetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/index.md).
- Restart a hot-swappable vault application:
[ReloadApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/ReloadApplication/index.md).
- Licenses: [SetVaultApplicationLicense](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetVaultApplicationLicense/index.md),
[GetVaultApplicationLicenseStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md).
- Uninstall: [RemoveScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/index.md).
**Enabled state.** `ExtApplication.is_enabled` is the default enabled state for clients, not
whether a vault application runs. A disabled vault application can show `is_enabled` true; ask
[GetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/index.md).
## Methods
| Method | Summary | Facts |
|---|---|---|
| [DownloadScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplication/index.md) | Not implemented: fails with "Not implemented.". | `write` `session` |
| [DownloadScriptApplicationFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md) | Starts downloading the package (ZIP file) of an application and returns its first block. | `read` `session` `idempotent` |
| [DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md) | Reads the next block of an application download. | `read` `session` `idempotent` |
| [GetClientScriptApplicationsDetails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetClientScriptApplicationsDetails/index.md) | Lists the enabled UI extension applications of the new M-Files clients with their modules, files and dashboards. | `read` `session` `idempotent` |
| [GetDownloadSessionIdOfScriptApplicationFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md) | Starts downloading one file of a UI extension application of the new M-Files clients. | `read` `session` `idempotent` |
| [GetScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplication/index.md) | Gets one application by its GUID. | `write` `session` |
| [GetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/index.md) | Tells whether an application is enabled in the vault. | `write` `session` |
| [GetScriptApplicationsEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationsEx/index.md) | Lists the applications installed in the vault, optionally only one type or platform. | `read` `session` `idempotent` |
| [GetVaultApplicationLicense](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicense/index.md) | Not implemented: always returns an empty `license`. | `write` `session` |
| [GetVaultApplicationLicenseStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md) | Gets the license status of a vault application, or checks a license before installing it. | `read` `session` `idempotent` |
| [ReloadApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/ReloadApplication/index.md) | Restarts a hot-swappable vault application on all servers of the vault. | `write` `session` |
| [RemoveScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/index.md) | Uninstalls an application from the vault. | `write` `session` |
| [SetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/index.md) | Enables or disables an application in the vault. | `write` `session` |
| [SetVaultApplicationLicense](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetVaultApplicationLicense/index.md) | Installs or removes the license of a vault application. | `write` `session` `idempotent` |
| [UploadScriptApplicationFileBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlock/index.md) | Uploads and installs an application package. Same as UploadScriptApplicationFileBlockEx without the list of outdated dependencies. | `write` `session` `idempotent` |
| [UploadScriptApplicationFileBlockEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/index.md) | Uploads an application package block by block and, with the last block, installs the application. | `write` `session` `idempotent` |
---
# IRPCClientScript.DownloadScriptApplication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplication/
Badges: `Vault API / standard` `write` `session`
Not implemented: fails with "Not implemented.".
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/DownloadScriptApplication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-script-application`
- **Request:** [`DownloadScriptApplicationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplication/index.md#request)
- **Response:** [`DownloadScriptApplicationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Download a package with
[DownloadScriptApplicationFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md).
## Request: DownloadScriptApplicationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The client application ID to download. |
| `resource_path` | `string` | Optional resource path inside the script application archive. |
## Response: DownloadScriptApplicationResponse
No fields.
## Related methods
- [DownloadScriptApplicationFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md): Starts downloading the package (ZIP file) of an application and returns its first block.
- [DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md): Reads the next block of an application download.
---
# IRPCClientScript.DownloadScriptApplicationFile_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/
Badges: `Vault API / standard` `read` `session` `idempotent`
Starts downloading the package (ZIP file) of an application and returns its first block.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-script-application-file_-begin`
- **Request:** [`DownloadScriptApplicationFile_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md#request)
- **Response:** [`DownloadScriptApplicationFile_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Continue with
[DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md)
from offset `len(data)` until `file_size` bytes have been read. If the first block already
holds the whole file, the download is finished and `download_id` cannot be used.
- `block_size` is at most 4194304 (4 MiB); larger values fail with "Block size exceeded the
limit of 4194304 bytes.". 0 returns no data.
## Request: DownloadScriptApplicationFile_BeginRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
| `block_size` | `uint32` | The number of bytes to return in `data`, at most 4 MiB. |
## Response: DownloadScriptApplicationFile_BeginResponse
> Nested 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 ID of the download, for the next blocks. |
| `file_size` | `int64` | The size of the package in bytes. |
| `data` | `bytes` | The first block of the package. |
## Related methods
- [DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md): Reads the next block of an application download.
- [DownloadScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplication/index.md): Not implemented: fails with "Not implemented.".
---
# IRPCClientScript.DownloadScriptApplicationFile_ReadBlock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/
Badges: `Vault API / standard` `read` `session` `idempotent`
Reads the next block of an application download.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-script-application-file_-read-block`
- **Request:** [`DownloadScriptApplicationFile_ReadBlockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md#request)
- **Response:** [`DownloadScriptApplicationFile_ReadBlockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Read the blocks in order. The download is removed after the read that reaches the end of the
file; later reads fail with "Not found. (The specified download session ... does not exist.)".
- Also reads downloads started with
[GetDownloadSessionIdOfScriptApplicationFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md).
## Request: DownloadScriptApplicationFile_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 ID of the download. |
| `block_size` | `uint32` | The number of bytes to read, at most 4 MiB. |
| `offset` | `int64` | The byte offset to read from. |
## Response: DownloadScriptApplicationFile_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. |
## Related methods
- [GetDownloadSessionIdOfScriptApplicationFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md): Starts downloading one file of a UI extension application of the new M-Files clients.
- [DownloadScriptApplicationFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_Begin/index.md): Starts downloading the package (ZIP file) of an application and returns its first block.
- [DownloadScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplication/index.md): Not implemented: fails with "Not implemented.".
---
# IRPCClientScript.GetClientScriptApplicationsDetails
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetClientScriptApplicationsDetails/
Badges: `Vault API / standard` `read` `session` `idempotent`
Lists the enabled UI extension applications of the new M-Files clients with their modules,
files and dashboards.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetClientScriptApplicationsDetails`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-client-script-applications-details`
- **Request:** [`GetClientScriptApplicationsDetailsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetClientScriptApplicationsDetails/index.md#request)
- **Response:** [`GetClientScriptApplicationsDetailsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetClientScriptApplicationsDetails/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Used by the M-Files clients to load UI extension applications; applications rarely call it.
- `platform` must be `EXT_APPLICATION_PLATFORM_VNEXT` or `EXT_APPLICATION_PLATFORM_ADMIN`; other
values fail with "The given platform is not supported.".
- Only client applications that support `EXT_APPLICATION_PLATFORM_VNEXT` are returned.
- Download a file of an application with
[GetDownloadSessionIdOfScriptApplicationFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md).
## Request: GetClientScriptApplicationsDetailsRequest
A structure that specifies applications detail 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 |
|---|---|---|
| `platform` | [`ExtApplicationPlatform`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationPlatform/index.md) | `EXT_APPLICATION_PLATFORM_VNEXT` or `EXT_APPLICATION_PLATFORM_ADMIN`. Values: `EXT_APPLICATION_PLATFORM_NONE` (0), `EXT_APPLICATION_PLATFORM_DESKTOP` (1), `EXT_APPLICATION_PLATFORM_WEB` (2), `EXT_APPLICATION_PLATFORM_SHARE_POINT_ADD_ON` (4), `EXT_APPLICATION_PLATFORM_VNEXT` (8), `EXT_APPLICATION_PLATFORM_MWIDGET` (16), `EXT_APPLICATION_PLATFORM_ADMIN` (32). |
## Response: GetClientScriptApplicationsDetailsResponse
A structure that specifies applications detail 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 |
|---|---|---|
| `applications[]` | repeated [`ExtApplicationDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplicationDef/index.md) | The applications with their modules and dashboards. See [ExtApplicationDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplicationDef/index.md). |
| `applications[].application` | [`ExtApplication`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplication/index.md) | The script application information. |
| `applications[].application.guid` | `string` | The application identifier. |
| `applications[].application.name` | `string` | The application name. |
| `applications[].application.version` | `string` | The application version (author set). |
| `applications[].application.description` | `string` | The application name. |
| `applications[].application.publisher` | `string` | The application publisher. |
| `applications[].application.is_enabled` | `bool` | True if the application is enabled. Note: this is a user-specific value and is not stored with the application data. Relevant for client applications only. |
| `applications[].application.is_optional` | `bool` | True if the application is optional (i.e. can be disabled). Relevant for client applications only. |
| `applications[].application.requires_system_access` | `bool` | True if this application requires system access. Relevant for client applications only. |
| `applications[].application.md5_checksum` | `string` | The application checksum (hash value). |
| `applications[].application.master_application` | `string` | The guid for the master application. GUID_NULL if there is no master application. |
| `applications[].application.type` | [`ExtApplicationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationType/index.md) | The application type. Values: `EXT_APPLICATION_TYPE_UNSPECIFIED` (0), `EXT_APPLICATION_TYPE_CLIENT` (1), `EXT_APPLICATION_TYPE_SERVER` (2). |
| `applications[].application.is_multi_server_compatible` | `bool` | Indicates if application has been designed to work in multi-server environment. |
| `applications[].application.published_at` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Publishing date. Zero values if date has not been defined. |
| `applications[].application.platforms` | `int32` | The binary value of the application platfroms supported. |
| `applications[].application.vault_app_dependencies[]` | repeated [`VaultApplicationDependency`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultApplicationDependency/index.md) | Vault application dependencies. |
| `applications[].application.is_signed_and_verified` | `bool` | True if the application is signed and has been verified. |
| `applications[].application.hot_swappable` | `bool` | True if the application can be deployed without vault restart. Applicable for server-side vault applications only. |
| `applications[].modules[]` | repeated [`ExtAppModuleDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtAppModuleDef/index.md) | The script application modules and files. |
| `applications[].modules[].application_guid` | `string` | The application identifier. |
| `applications[].modules[].script_engine` | [`ExtAppEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtAppEngine/index.md) | The script engine that can run this module. Values: `EXT_APP_ENGINE_UNKNOWN` (0), `EXT_APP_ENGINE_SHELL_UI` (1), `EXT_APP_ENGINE_VAULT_UI` (2), `EXT_APP_ENGINE_VAULT_CORE` (3). |
| `applications[].modules[].application_path` | `string` | Path to the application folder. |
| `applications[].modules[].module_name` | `string` | The module name. |
| `applications[].modules[].script_engine_definition` | `string` | The engine defintion for script engine that runs this module. |
| `applications[].modules[].event_priority` | `int32` | The event priority for this module. |
| `applications[].modules[].fast_browsing_compatible` | `bool` | Tells if the module is fast-browsing compatible. Effective only for shellui modules. |
| `applications[].modules[].files[]` | repeated `string` | Array of file names (String). Relative to the application path. |
| `applications[].modules[].sandbox_attributes` | `string` | The sandbox attributes. |
| `applications[].dashboards[]` | repeated [`ExtAppDashboardDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtAppDashboardDef/index.md) | The script application dashboards. |
| `applications[].dashboards[].application_guid` | `string` | The application identifier. |
| `applications[].dashboards[].dashboard_id` | `string` | The dashboard ID. |
| `applications[].dashboards[].application_path` | `string` | Path to the application folder. |
| `applications[].dashboards[].dashboard_name` | `string` | The dashboard name. |
| `applications[].dashboards[].content_file` | `string` | The initial content file for the dashboard. Relative to the application path. |
| `applications[].dashboards[].event_priority` | `int32` | The event priority for this dashboard. |
| `applications[].dashboards[].trusted_content_urls[]` | repeated `string` | Array of trusted contents (String). |
| `applications[].dashboards[].internal_app` | `bool` | True if the application is launched as an internal application. This relaxes some validations. |
| `applications[].dashboards[].allow_text_selection` | `bool` | True to allow text selection in browser. |
| `applications[].dashboards[].icon_path` | `string` | Path to application's icon. |
| `applications[].dashboards[].icon_selected_path` | `string` | Path to application's icon when it is selected. |
| `applications[].dashboards[].sandbox_attributes` | `string` | The sandbox attributes. |
## Related methods
- [GetDownloadSessionIdOfScriptApplicationFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md): Starts downloading one file of a UI extension application of the new M-Files clients.
---
# IRPCClientScript.GetDownloadSessionIdOfScriptApplicationFile
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/
Badges: `Vault API / standard` `read` `session` `idempotent`
Starts downloading one file of a UI extension application of the new M-Files clients.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-download-session-id-of-script-application-file`
- **Request:** [`GetDownloadSessionIdOfScriptApplicationFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md#request)
- **Response:** [`GetDownloadSessionIdOfScriptApplicationFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetDownloadSessionIdOfScriptApplicationFile/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Used by the M-Files clients to load UI extension applications; applications rarely call it.
- Only for client applications that support `EXT_APPLICATION_PLATFORM_VNEXT`; others fail with
"The script application is not a client app or the platform is not supported.".
- `file_name` is relative to the application folder. Absolute paths and `..` components are
rejected; a file that does not exist fails with "Not found.".
- Read the file with
[DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md).
## Request: GetDownloadSessionIdOfScriptApplicationFileRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
| `file_name` | `string` | The path of the file inside the application, for example `script\helper.js`. |
## Response: GetDownloadSessionIdOfScriptApplicationFileResponse
> Nested 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 ID of the download. |
| `file_size` | `int64` | The size of the file in bytes. |
## Related methods
- [DownloadScriptApplicationFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/DownloadScriptApplicationFile_ReadBlock/index.md): Reads the next block of an application download.
---
# IRPCClientScript.GetScriptApplication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplication/
Badges: `Vault API / standard` `write` `session`
Gets one application by its GUID.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetScriptApplication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-script-application`
- **Request:** [`GetScriptApplicationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplication/index.md#request)
- **Response:** [`GetScriptApplicationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- An unknown GUID fails with "Not found. (Vault application not found. (ID: ...))".
## Request: GetScriptApplicationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
## Response: GetScriptApplicationResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `application` | [`ExtApplication`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplication/index.md) | The application. See [ExtApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplication/index.md). |
| `application.guid` | `string` | The application identifier. |
| `application.name` | `string` | The application name. |
| `application.version` | `string` | The application version (author set). |
| `application.description` | `string` | The application name. |
| `application.publisher` | `string` | The application publisher. |
| `application.is_enabled` | `bool` | True if the application is enabled. Note: this is a user-specific value and is not stored with the application data. Relevant for client applications only. |
| `application.is_optional` | `bool` | True if the application is optional (i.e. can be disabled). Relevant for client applications only. |
| `application.requires_system_access` | `bool` | True if this application requires system access. Relevant for client applications only. |
| `application.md5_checksum` | `string` | The application checksum (hash value). |
| `application.master_application` | `string` | The guid for the master application. GUID_NULL if there is no master application. |
| `application.type` | [`ExtApplicationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationType/index.md) | The application type. Values: `EXT_APPLICATION_TYPE_UNSPECIFIED` (0), `EXT_APPLICATION_TYPE_CLIENT` (1), `EXT_APPLICATION_TYPE_SERVER` (2). |
| `application.is_multi_server_compatible` | `bool` | Indicates if application has been designed to work in multi-server environment. |
| `application.published_at` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Publishing date. Zero values if date has not been defined. |
| `application.platforms` | `int32` | The binary value of the application platfroms supported. |
| `application.vault_app_dependencies[]` | repeated [`VaultApplicationDependency`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultApplicationDependency/index.md) | Vault application dependencies. |
| `application.vault_app_dependencies[].guid` | `string` | The application identifier. |
| `application.vault_app_dependencies[].name` | `string` | The name of the required vault application. |
| `application.vault_app_dependencies[].version` | `string` | The minimum required application version. |
| `application.vault_app_dependencies[].required` | `bool` | True if the application is required to be at at least the minimum version. |
| `application.is_signed_and_verified` | `bool` | True if the application is signed and has been verified. |
| `application.hot_swappable` | `bool` | True if the application can be deployed without vault restart. Applicable for server-side vault applications only. |
## Related methods
- [GetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/index.md): Tells whether an application is enabled in the vault.
---
# IRPCClientScript.GetScriptApplicationServerEnable
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/
Badges: `Vault API / standard` `write` `session`
Tells whether an application is enabled in the vault.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetScriptApplicationServerEnable`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-script-application-server-enable`
- **Request:** [`GetScriptApplicationServerEnableRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/index.md#request)
- **Response:** [`GetScriptApplicationServerEnableResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationServerEnable/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- This is the real enabled state; `ExtApplication.is_enabled` is not.
## Request: GetScriptApplicationServerEnableRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
## Response: GetScriptApplicationServerEnableResponse
> Nested 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 application is enabled. |
## Related methods
- [GetScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplication/index.md): Gets one application by its GUID.
---
# IRPCClientScript.GetScriptApplicationsEx
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationsEx/
Badges: `Vault API / standard` `read` `session` `idempotent`
Lists the applications installed in the vault, optionally only one type or platform.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetScriptApplicationsEx`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-script-applications-ex`
- **Request:** [`GetScriptApplicationsExRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationsEx/index.md#request)
- **Response:** [`GetScriptApplicationsExResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetScriptApplicationsEx/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- With `filter` `EXT_APPLICATION_TYPE_CLIENT` any vault session can call it. Other filters need
the vault right `read_all_metadata_structure`; otherwise "Access denied.".
- With `filter` `EXT_APPLICATION_TYPE_UNSPECIFIED` all applications are returned, disabled ones
included. With a type filter only enabled applications are returned; UI extension
applications whose vault application is disabled are left out as well.
- `platform` returns the applications whose `platforms` include it.
`EXT_APPLICATION_PLATFORM_NONE` and `EXT_APPLICATION_PLATFORM_ADMIN` do not filter.
## Request: GetScriptApplicationsExRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `filter` | [`ExtApplicationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationType/index.md) | The application type, or `EXT_APPLICATION_TYPE_UNSPECIFIED` for all types (disabled applications included). Values: `EXT_APPLICATION_TYPE_UNSPECIFIED` (0), `EXT_APPLICATION_TYPE_CLIENT` (1), `EXT_APPLICATION_TYPE_SERVER` (2). |
| `platform` | [`ExtApplicationPlatform`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationPlatform/index.md) | The client platform, or `EXT_APPLICATION_PLATFORM_NONE` for all. Values: `EXT_APPLICATION_PLATFORM_NONE` (0), `EXT_APPLICATION_PLATFORM_DESKTOP` (1), `EXT_APPLICATION_PLATFORM_WEB` (2), `EXT_APPLICATION_PLATFORM_SHARE_POINT_ADD_ON` (4), `EXT_APPLICATION_PLATFORM_VNEXT` (8), `EXT_APPLICATION_PLATFORM_MWIDGET` (16), `EXT_APPLICATION_PLATFORM_ADMIN` (32). |
## Response: GetScriptApplicationsExResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `applications[]` | repeated [`ExtApplication`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplication/index.md) | The applications. See [ExtApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtApplication/index.md). |
| `applications[].guid` | `string` | The application identifier. |
| `applications[].name` | `string` | The application name. |
| `applications[].version` | `string` | The application version (author set). |
| `applications[].description` | `string` | The application name. |
| `applications[].publisher` | `string` | The application publisher. |
| `applications[].is_enabled` | `bool` | True if the application is enabled. Note: this is a user-specific value and is not stored with the application data. Relevant for client applications only. |
| `applications[].is_optional` | `bool` | True if the application is optional (i.e. can be disabled). Relevant for client applications only. |
| `applications[].requires_system_access` | `bool` | True if this application requires system access. Relevant for client applications only. |
| `applications[].md5_checksum` | `string` | The application checksum (hash value). |
| `applications[].master_application` | `string` | The guid for the master application. GUID_NULL if there is no master application. |
| `applications[].type` | [`ExtApplicationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtApplicationType/index.md) | The application type. Values: `EXT_APPLICATION_TYPE_UNSPECIFIED` (0), `EXT_APPLICATION_TYPE_CLIENT` (1), `EXT_APPLICATION_TYPE_SERVER` (2). |
| `applications[].is_multi_server_compatible` | `bool` | Indicates if application has been designed to work in multi-server environment. |
| `applications[].published_at` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Publishing date. Zero values if date has not been defined. |
| `applications[].platforms` | `int32` | The binary value of the application platfroms supported. |
| `applications[].vault_app_dependencies[]` | repeated [`VaultApplicationDependency`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultApplicationDependency/index.md) | Vault application dependencies. |
| `applications[].vault_app_dependencies[].guid` | `string` | The application identifier. |
| `applications[].vault_app_dependencies[].name` | `string` | The name of the required vault application. |
| `applications[].vault_app_dependencies[].version` | `string` | The minimum required application version. |
| `applications[].vault_app_dependencies[].required` | `bool` | True if the application is required to be at at least the minimum version. |
| `applications[].is_signed_and_verified` | `bool` | True if the application is signed and has been verified. |
| `applications[].hot_swappable` | `bool` | True if the application can be deployed without vault restart. Applicable for server-side vault applications only. |
---
# IRPCClientScript.GetVaultApplicationLicense
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicense/
Badges: `Vault API / standard` `write` `session`
Not implemented: always returns an empty `license`.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetVaultApplicationLicense`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-application-license`
- **Request:** [`GetVaultApplicationLicenseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicense/index.md#request)
- **Response:** [`GetVaultApplicationLicenseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicense/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Use [GetVaultApplicationLicenseStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md)
to check a license.
## Request: GetVaultApplicationLicenseRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
## Response: GetVaultApplicationLicenseResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `license` | `string` | Always empty. |
## Related methods
- [GetVaultApplicationLicenseStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md): Gets the license status of a vault application, or checks a license before installing it.
---
# IRPCClientScript.GetVaultApplicationLicenseStatus
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/
Badges: `Vault API / standard` `read` `session` `idempotent`
Gets the license status of a vault application, or checks a license before installing it.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-application-license-status`
- **Request:** [`GetVaultApplicationLicenseStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md#request)
- **Response:** [`GetVaultApplicationLicenseStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- The status comes from the running application. If the application is not running (for
example, it is disabled), the status is `APPLICATION_LICENSE_STATUS_INSTALLED` or
`APPLICATION_LICENSE_STATUS_NOT_INSTALLED` depending on whether a license is stored.
- With `use_new_license` the application evaluates `new_license` without storing it.
## Request: GetVaultApplicationLicenseStatusRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `application_guid` | `string` | The GUID of the application. |
| `use_new_license` | `bool` | True to evaluate `new_license` instead of the installed license. |
| `new_license` | `string` | The license to evaluate when `use_new_license` is true. |
| `return_details` | `bool` | True to get a description of the status in `details`. |
## Response: GetVaultApplicationLicenseStatusResponse
> Nested 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` | [`ApplicationLicenseStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ApplicationLicenseStatus/index.md) | The license status of the application. Values: `APPLICATION_LICENSE_STATUS_UNKNOWN` (0), `APPLICATION_LICENSE_STATUS_NOT_NEEDED` (1), `APPLICATION_LICENSE_STATUS_NOT_INSTALLED` (2), `APPLICATION_LICENSE_STATUS_INSTALLED` (3), `APPLICATION_LICENSE_STATUS_VALID` (4), `APPLICATION_LICENSE_STATUS_INVALID` (5), `APPLICATION_LICENSE_STATUS_FORMAT_ERROR` (6), `APPLICATION_LICENSE_STATUS_TRIAL` (7), `APPLICATION_LICENSE_STATUS_GRACE_PERIOD` (8). |
| `details` | `string` | With `return_details`, a description of the status. |
## Related methods
- [GetVaultApplicationLicense](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicense/index.md): Not implemented: always returns an empty `license`.
---
# IRPCClientScript.ReloadApplication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/ReloadApplication/
Badges: `Vault API / standard` `write` `session`
Restarts a hot-swappable vault application on all servers of the vault.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/ReloadApplication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reload-application`
- **Request:** [`ReloadApplicationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/ReloadApplication/index.md#request)
- **Response:** [`ReloadApplicationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/ReloadApplication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- Applies to applications with `ExtApplication.hot_swappable` true. The request is sent to the
servers of the vault as a broadcast message; the call returns before the application has
restarted.
## Request: ReloadApplicationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `application` | `string` | The GUID of the vault application. |
## Response: ReloadApplicationResponse
No fields.
---
# IRPCClientScript.RemoveScriptApplication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/
Badges: `Vault API / standard` `write` `session`
Uninstalls an application from the vault.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/RemoveScriptApplication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-script-application`
- **Request:** [`RemoveScriptApplicationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/index.md#request)
- **Response:** [`RemoveScriptApplicationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- Applications that have this application as their master application are uninstalled too.
- An unknown GUID fails with "Not found.".
- To stop a vault application without uninstalling it, use
[SetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/index.md).
## Request: RemoveScriptApplicationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application to uninstall. |
## Response: RemoveScriptApplicationResponse
No fields.
## Related methods
- [SetScriptApplicationServerEnable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/index.md): Enables or disables an application in the vault.
---
# IRPCClientScript.SetScriptApplicationServerEnable
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/
Badges: `Vault API / standard` `write` `session`
Enables or disables an application in the vault.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/SetScriptApplicationServerEnable`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-script-application-server-enable`
- **Request:** [`SetScriptApplicationServerEnableRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/index.md#request)
- **Response:** [`SetScriptApplicationServerEnableResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetScriptApplicationServerEnable/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- An application whose master application is disabled cannot be enabled.
- Disabling also disables the applications that have this application as their master.
## Request: SetScriptApplicationServerEnableRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
| `enabled` | `bool` | True to enable, false to disable. |
## Response: SetScriptApplicationServerEnableResponse
No fields.
---
# IRPCClientScript.SetVaultApplicationLicense
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetVaultApplicationLicense/
Badges: `Vault API / standard` `write` `session` `idempotent`
Installs or removes the license of a vault application.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/SetVaultApplicationLicense`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-vault-application-license`
- **Request:** [`SetVaultApplicationLicenseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetVaultApplicationLicense/index.md#request)
- **Response:** [`SetVaultApplicationLicenseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/SetVaultApplicationLicense/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- An empty `license` removes the license. A license that the application reports as malformed
is rejected.
- The new license is passed to the running application. Check the result with
[GetVaultApplicationLicenseStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md).
## Request: SetVaultApplicationLicenseRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `script_application` | `string` | The GUID of the application. |
| `license` | `string` | The content of the license file; empty to remove the license. |
## Response: SetVaultApplicationLicenseResponse
No fields.
## Related methods
- [GetVaultApplicationLicenseStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/GetVaultApplicationLicenseStatus/index.md): Gets the license status of a vault application, or checks a license before installing it.
---
# IRPCClientScript.UploadScriptApplicationFileBlock
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlock/
Badges: `Vault API / standard` `write` `session` `idempotent`
Uploads and installs an application package. Same as UploadScriptApplicationFileBlockEx
without the list of outdated dependencies.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/UploadScriptApplicationFileBlock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-script-application-file-block`
- **Request:** [`UploadScriptApplicationFileBlockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlock/index.md#request)
- **Response:** [`UploadScriptApplicationFileBlockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlock/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- See [UploadScriptApplicationFileBlockEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/index.md),
which new code should use.
## Request: UploadScriptApplicationFileBlockRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | 0 in the first call; then the `upload_idret` it returned. |
| `total_size_in_bytes` | `int64` | The total size of the file in bytes. |
| `offset` | `int64` | Starting position. NOTE: Always use multiples of 4096 bytes. |
| `data` | `bytes` | The file block to append. |
| `ready` | `bool` | True on the last block, to install the uploaded package. |
## Response: UploadScriptApplicationFileBlockResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_idret` | `int32` | The ID of the upload, for the next blocks. |
## Related methods
- [UploadScriptApplicationFileBlockEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/index.md): Uploads an application package block by block and, with the last block, installs the application.
---
# IRPCClientScript.UploadScriptApplicationFileBlockEx
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/
Badges: `Vault API / standard` `write` `session` `idempotent`
Uploads an application package block by block and, with the last block, installs the
application.
- **Service:** [Client scripts and UI extension applications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/index.md) `MFiles.IRPCClientScript`
- **gRPC method:** `/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-script-application-file-block-ex`
- **Request:** [`UploadScriptApplicationFileBlockExRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/index.md#request)
- **Response:** [`UploadScriptApplicationFileBlockExResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlockEx/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault right `change_metadata_structure`.
- First call: `upload_id` 0 and `offset` 0; it returns the new ID in `upload_idret`. Send the
following blocks with that ID and their offsets, and set `ready` on the last block. The
package may be at most 500 MB.
- With `ready` the server validates and installs the package. It is rejected if the same
version is already installed ("Already exists."), if it is older than the installed version,
if it is not a valid application package, or if it is an unsigned vault application and the
server requires a valid signature from the caller.
- `outdated_vault_apps` lists the vault applications that this application depends on and whose
installed version is lower than it requires.
- Uninstall with [RemoveScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/index.md).
## Request: UploadScriptApplicationFileBlockExRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | 0 in the first call; then the `upload_idret` it returned. |
| `total_size_in_bytes` | `int64` | The size of the whole package. |
| `offset` | `int64` | The position of this block. Use multiples of 4096 bytes for all blocks but the last. |
| `data` | `bytes` | The bytes of this block. |
| `ready` | `bool` | True on the last block, to install the uploaded package. |
## Response: UploadScriptApplicationFileBlockExResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_idret` | `int32` | The ID of the upload, for the next blocks. |
| `outdated_vault_apps[]` | repeated [`VaultApplicationDependency`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultApplicationDependency/index.md) | After the last block, the dependencies whose installed version is too old. Empty otherwise. |
| `outdated_vault_apps[].guid` | `string` | The application identifier. |
| `outdated_vault_apps[].name` | `string` | The name of the required vault application. |
| `outdated_vault_apps[].version` | `string` | The minimum required application version. |
| `outdated_vault_apps[].required` | `bool` | True if the application is required to be at at least the minimum version. |
## Related methods
- [RemoveScriptApplication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/RemoveScriptApplication/index.md): Uninstalls an application from the vault.
- [UploadScriptApplicationFileBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCClientScript/UploadScriptApplicationFileBlock/index.md): Uploads and installs an application package. Same as UploadScriptApplicationFileBlockEx without the list of outdated dependencies.
---
# Conversations (IRPCConversationOperations)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/
Stores conversations with Aino and their chat turns in the vault, per user.
- **gRPC service:** `MFiles.IRPCConversationOperations`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 6
- **Proto file:** [`mfiles/IRPCConversationOperations.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCConversationOperations.proto)
## Overview
A per-user history store for chat-style features. A
[Conversation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Conversation/index.md) has a title and a type; its
[ChatTurn](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ChatTurn/index.md)s hold the exchanged messages as text that the server stores
without interpreting it. The vault does not run any agent here: the caller writes what it wants
to keep.
- **Create or rename a conversation**:
[AddOrUpdateConversation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateConversation/index.md).
- **Add or change a chat turn**:
[AddOrUpdateChatTurn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateChatTurn/index.md).
- **Read**: [GetConversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversations/index.md),
[GetConversationById](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversationById/index.md),
[GetChatTurns](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetChatTurns/index.md).
- **Delete** a conversation with its chat turns:
[DeleteConversationById](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/DeleteConversationById/index.md).
All methods need a vault session and no special vault rights. A conversation belongs to the user
who created it; reading, renaming or deleting another user's conversation fails with "Access is
denied.". Administrators get no exception.
**Paging.** [GetConversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversations/index.md) and
[GetChatTurns](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetChatTurns/index.md) return at most 100 items,
newest first (descending `sort_key`). For the next page, send the smallest `sort_key` you
received; the server returns the items whose `sort_key` is less than it. 0 starts from the
newest. `more_results` is true while older items remain.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AddOrUpdateChatTurn](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateChatTurn/index.md) | Adds a chat turn to one of the caller's conversations, or replaces the content of an existing chat turn. | `write` `session` |
| [AddOrUpdateConversation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateConversation/index.md) | Creates a conversation, or renames an existing one of the caller. | `write` `session` |
| [DeleteConversationById](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/DeleteConversationById/index.md) | Deletes one of the caller's conversations and all its chat turns. | `write` `session` |
| [GetChatTurns](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetChatTurns/index.md) | Gets the chat turns of one of the caller's conversations, newest first, up to 100 per call. | `write` `session` |
| [GetConversationById](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversationById/index.md) | Gets one of the caller's conversations by ID. | `write` `session` |
| [GetConversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversations/index.md) | Gets the caller's conversations, newest first, up to 100 per call. | `write` `session` |
---
# IRPCConversationOperations.AddOrUpdateChatTurn
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateChatTurn/
Badges: `Vault API / standard` `write` `session`
Adds a chat turn to one of the caller's conversations, or replaces the content of an existing
chat turn.
- **Service:** [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `MFiles.IRPCConversationOperations`
- **gRPC method:** `/MFiles.IRPCConversationOperations/AddOrUpdateChatTurn`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-or-update-chat-turn`
- **Request:** [`AddOrUpdateChatTurnRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateChatTurn/index.md#request)
- **Response:** [`AddOrUpdateChatTurnResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateChatTurn/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- `conv_id` must name an existing conversation; otherwise the call fails with "The parameter is
incorrect.".
- With `id` 0, or an ID that does not exist, a new chat turn is added with a new ID and
`sort_key`. With an existing ID, `chat_turn` replaces the stored content and `modified` is
updated.
- The content is stored as given; the server does not parse it.
## Request: AddOrUpdateChatTurnRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `chat_turn` | [`ChatTurn`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ChatTurn/index.md) | The chat turn. Set `conv_id` and `chat_turn` (the content); set `id` to replace an existing turn. |
| `chat_turn.id` | `uint32` | The ID of the chat turn, assigned by the server. |
| `chat_turn.conv_id` | `uint32` | The ID of the conversation the turn belongs to. |
| `chat_turn.chat_turn` | `string` | The content of the turn as text. The server stores it as given and does not parse it; the format is up to the caller. |
| `chat_turn.sort_key` | `uint32` | Orders the turns; newer turns have larger values. Used for paging. |
| `chat_turn.created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the turn was added (UTC). |
| `chat_turn.modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the turn was added or last replaced (UTC). |
## Response: AddOrUpdateChatTurnResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_chat_turn` | [`ChatTurn`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ChatTurn/index.md) | The chat turn as stored, with its ID and `sort_key`. |
| `updated_chat_turn.id` | `uint32` | The ID of the chat turn, assigned by the server. |
| `updated_chat_turn.conv_id` | `uint32` | The ID of the conversation the turn belongs to. |
| `updated_chat_turn.chat_turn` | `string` | The content of the turn as text. The server stores it as given and does not parse it; the format is up to the caller. |
| `updated_chat_turn.sort_key` | `uint32` | Orders the turns; newer turns have larger values. Used for paging. |
| `updated_chat_turn.created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the turn was added (UTC). |
| `updated_chat_turn.modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the turn was added or last replaced (UTC). |
---
# IRPCConversationOperations.AddOrUpdateConversation
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateConversation/
Badges: `Vault API / standard` `write` `session`
Creates a conversation, or renames an existing one of the caller.
- **Service:** [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `MFiles.IRPCConversationOperations`
- **gRPC method:** `/MFiles.IRPCConversationOperations/AddOrUpdateConversation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-or-update-conversation`
- **Request:** [`AddOrUpdateConversationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateConversation/index.md#request)
- **Response:** [`AddOrUpdateConversationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/AddOrUpdateConversation/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- With `id` 0, or an ID that does not exist, the server creates a new conversation with a new
ID and `sort_key`, owned by the caller. Read the new ID from the response.
- With the ID of an existing conversation of the caller, only `title` is changed and `modified`
is updated; `type` cannot be changed. The conversation of another user fails with "Access is
denied.".
- `user_id`, `sort_key`, `created` and `modified` in the request are ignored.
## Request: AddOrUpdateConversationRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `conversation` | [`Conversation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Conversation/index.md) | The conversation. Set `title` and, for a new one, `type`; set `id` to rename an existing one. |
| `conversation.id` | `uint32` | The ID of the conversation, assigned by the server. |
| `conversation.user_id` | `uint32` | The ID of the user account that owns the conversation. Set by the server. |
| `conversation.type` | [`ConversationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConversationType/index.md) | The kind of conversation. Set when the conversation is created. Values: `CONVERSATION_TYPE_UNDEFINED` (0), `CONVERSATION_TYPE_AINO` (1). |
| `conversation.title` | `string` | The title of the conversation, as plain text. |
| `conversation.sort_key` | `uint32` | Orders conversations; newer conversations have larger values. Used for paging. |
| `conversation.created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created (UTC). |
| `conversation.modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created or last renamed (UTC). |
## Response: AddOrUpdateConversationResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_conversation` | [`Conversation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Conversation/index.md) | The conversation as stored. |
| `updated_conversation.id` | `uint32` | The ID of the conversation, assigned by the server. |
| `updated_conversation.user_id` | `uint32` | The ID of the user account that owns the conversation. Set by the server. |
| `updated_conversation.type` | [`ConversationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConversationType/index.md) | The kind of conversation. Set when the conversation is created. Values: `CONVERSATION_TYPE_UNDEFINED` (0), `CONVERSATION_TYPE_AINO` (1). |
| `updated_conversation.title` | `string` | The title of the conversation, as plain text. |
| `updated_conversation.sort_key` | `uint32` | Orders conversations; newer conversations have larger values. Used for paging. |
| `updated_conversation.created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created (UTC). |
| `updated_conversation.modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created or last renamed (UTC). |
---
# IRPCConversationOperations.DeleteConversationById
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/DeleteConversationById/
Badges: `Vault API / standard` `write` `session`
Deletes one of the caller's conversations and all its chat turns.
- **Service:** [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `MFiles.IRPCConversationOperations`
- **gRPC method:** `/MFiles.IRPCConversationOperations/DeleteConversationById`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/delete-conversation-by-id`
- **Request:** [`DeleteConversationByIdRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/DeleteConversationById/index.md#request)
- **Response:** [`DeleteConversationByIdResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/DeleteConversationById/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- A conversation of another user fails with "Access is denied."; an ID that does not exist
fails with "The parameter is incorrect.".
- Deleted conversations are no longer returned. The server keeps an archived copy of them and
of their chat turns.
## Request: DeleteConversationByIdRequest
> Nested 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` | `uint32` | The ID of the conversation. |
## Response: DeleteConversationByIdResponse
No fields.
---
# IRPCConversationOperations.GetChatTurns
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetChatTurns/
Badges: `Vault API / standard` `write` `session`
Gets the chat turns of one of the caller's conversations, newest first, up to 100 per call.
- **Service:** [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `MFiles.IRPCConversationOperations`
- **gRPC method:** `/MFiles.IRPCConversationOperations/GetChatTurns`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-chat-turns`
- **Request:** [`GetChatTurnsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetChatTurns/index.md#request)
- **Response:** [`GetChatTurnsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetChatTurns/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- The conversation must belong to the caller; otherwise the call fails with "Access is
denied.". See the service overview for paging.
## Request: GetChatTurnsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `conversation_id` | `uint32` | The ID of the conversation. |
| `sort_key` | `uint32` | 0 for the first page; for the next page, the smallest `sort_key` of the previous page. |
## Response: GetChatTurnsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `chat_turns[]` | repeated [`ChatTurn`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ChatTurn/index.md) | Up to 100 chat turns in descending `sort_key` order. |
| `chat_turns[].id` | `uint32` | The ID of the chat turn, assigned by the server. |
| `chat_turns[].conv_id` | `uint32` | The ID of the conversation the turn belongs to. |
| `chat_turns[].chat_turn` | `string` | The content of the turn as text. The server stores it as given and does not parse it; the format is up to the caller. |
| `chat_turns[].sort_key` | `uint32` | Orders the turns; newer turns have larger values. Used for paging. |
| `chat_turns[].created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the turn was added (UTC). |
| `chat_turns[].modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the turn was added or last replaced (UTC). |
| `more_results` | `bool` | True if older chat turns remain. |
---
# IRPCConversationOperations.GetConversationById
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversationById/
Badges: `Vault API / standard` `write` `session`
Gets one of the caller's conversations by ID.
- **Service:** [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `MFiles.IRPCConversationOperations`
- **gRPC method:** `/MFiles.IRPCConversationOperations/GetConversationById`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-conversation-by-id`
- **Request:** [`GetConversationByIdRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversationById/index.md#request)
- **Response:** [`GetConversationByIdResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversationById/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- A conversation of another user, or an ID that does not exist, fails with "Access is
denied.". ID 0 fails with "The parameter is incorrect.".
## Request: GetConversationByIdRequest
> Nested 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` | `uint32` | The ID of the conversation. |
## Response: GetConversationByIdResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `updated_conversation` | [`Conversation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Conversation/index.md) | The requested conversation of the caller. |
| `updated_conversation.id` | `uint32` | The ID of the conversation, assigned by the server. |
| `updated_conversation.user_id` | `uint32` | The ID of the user account that owns the conversation. Set by the server. |
| `updated_conversation.type` | [`ConversationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConversationType/index.md) | The kind of conversation. Set when the conversation is created. Values: `CONVERSATION_TYPE_UNDEFINED` (0), `CONVERSATION_TYPE_AINO` (1). |
| `updated_conversation.title` | `string` | The title of the conversation, as plain text. |
| `updated_conversation.sort_key` | `uint32` | Orders conversations; newer conversations have larger values. Used for paging. |
| `updated_conversation.created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created (UTC). |
| `updated_conversation.modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created or last renamed (UTC). |
---
# IRPCConversationOperations.GetConversations
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversations/
Badges: `Vault API / standard` `write` `session`
Gets the caller's conversations, newest first, up to 100 per call.
- **Service:** [Conversations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/index.md) `MFiles.IRPCConversationOperations`
- **gRPC method:** `/MFiles.IRPCConversationOperations/GetConversations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-conversations`
- **Request:** [`GetConversationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversations/index.md#request)
- **Response:** [`GetConversationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCConversationOperations/GetConversations/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Returns only the caller's own conversations. See the service overview for paging.
## Request: GetConversationsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `sort_key` | `uint32` | 0 for the first page; for the next page, the smallest `sort_key` of the previous page. |
## Response: GetConversationsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `conversations[]` | repeated [`Conversation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Conversation/index.md) | Up to 100 conversations in descending `sort_key` order. |
| `conversations[].id` | `uint32` | The ID of the conversation, assigned by the server. |
| `conversations[].user_id` | `uint32` | The ID of the user account that owns the conversation. Set by the server. |
| `conversations[].type` | [`ConversationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConversationType/index.md) | The kind of conversation. Set when the conversation is created. Values: `CONVERSATION_TYPE_UNDEFINED` (0), `CONVERSATION_TYPE_AINO` (1). |
| `conversations[].title` | `string` | The title of the conversation, as plain text. |
| `conversations[].sort_key` | `uint32` | Orders conversations; newer conversations have larger values. Used for paging. |
| `conversations[].created` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created (UTC). |
| `conversations[].modified` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the conversation was created or last renamed (UTC). |
| `more_results` | `bool` | True if older conversations remain. |
---
# Aino agents (IRPCAgent)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/
Connects M-Files clients to the Aino agents of M-Files Cloud.
- **gRPC service:** `MFiles.IRPCAgent`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCAgent.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCAgent.proto)
## Overview
The M-Files clients use this service for Aino features. The server forwards each request to
the Aino agent service on behalf of the session's user and returns the agent's answer. The
payloads are text documents in formats defined by the M-Files clients and the agent service,
and they change with them; applications should not depend on them.
- [AgentCreateSummarization](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/AgentCreateSummarization/index.md): a summary of a
set of objects.
- [CreateAgentResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CreateAgentResponse/index.md): one turn with the
general Aino agent.
- [CallAgentApiV2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CallAgentApiV2/index.md): a call to version 2 of the agent
service API.
Prerequisites: a vault session of a user, and a vault whose subscription includes Aino; without
it the calls fail with "Your current subscription does not include the specified feature.".
Methods that are not available on the server fail with "Not implemented.". When the agent
service cannot be reached, or fails, the call fails with "Aino agent request failed." (or "Aino
Summarization failed."); the details are only in the server log.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [AgentCreateSummarization](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/AgentCreateSummarization/index.md) | Creates an Aino summary of a set of objects. Used by M-Files clients; the request and response formats are internal to them. | `write` `session` `idempotent` `returns metadata structure version` |
| [CallAgentApiV2](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CallAgentApiV2/index.md) | Calls version 2 of the Aino agent service API for the session's user and returns the HTTP status and body. A temporary bridge for M-Files clients that cannot call the agent service directly; it will be deprecated when they can. | `write` `session` `returns metadata structure version` |
| [CreateAgentResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CreateAgentResponse/index.md) | Sends one turn to the general Aino agent and returns its answer. Used by M-Files clients; the request and response formats are internal to them. | `write` `session` `idempotent` `returns metadata structure version` |
---
# IRPCAgent.AgentCreateSummarization
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/AgentCreateSummarization/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Creates an Aino summary of a set of objects. Used by M-Files clients; the request and response
formats are internal to them.
- **Service:** [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md) `MFiles.IRPCAgent`
- **gRPC method:** `/MFiles.IRPCAgent/AgentCreateSummarization`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/agent-create-summarization`
- **Request:** [`AgentRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AgentRequest/index.md)
- **Response:** [`AgentResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AgentResponse/index.md)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session of a user and a vault where Aino summarization is available.
- The server checks that the caller can read every object named in the request; if not, the
call fails and nothing is sent to the agent.
- Same operation as [CreateSummarization](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/CreateSummarization/index.md).
## Request: AgentRequest
A request to an Aino agent.
> Nested 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` | `string` | The request document, in a format internal to the M-Files clients. |
## Response: AgentResponse
The answer of an Aino agent.
> Nested 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` | `string` | The answer document, in a format internal to the M-Files clients. |
## Related methods
- [IRPCSearch.CreateSummarization](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/CreateSummarization/index.md): Creates an Aino summary for the M-Files clients.
---
# IRPCAgent.CallAgentApiV2
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CallAgentApiV2/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Calls version 2 of the Aino agent service API for the session's user and returns the HTTP
status and body. A temporary bridge for M-Files clients that cannot call the agent service
directly; it will be deprecated when they can.
- **Service:** [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md) `MFiles.IRPCAgent`
- **gRPC method:** `/MFiles.IRPCAgent/CallAgentApiV2`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/call-agent-api-v2`
- **Request:** [`AgentApiV2Request`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CallAgentApiV2/index.md#request)
- **Response:** [`AgentApiV2Response`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CallAgentApiV2/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session of a user and a vault whose subscription includes Aino.
- The server fixes the API version, the subscription and the vault (the session's). The
request gives only the path below the vault, the HTTP method and the body.
- `path` may contain only letters, digits, `.`, `_`, `~`, `-` and `/`, with no empty, `.` or
`..` segments; there is no query string. `method` may be GET, POST (the default), PUT, PATCH
or DELETE. Other values fail with "The parameter is incorrect.".
- `parameters` must be empty or a JSON object. The server adds its own member
`_mfserverData` to it (information about the user and the vault that the agent service needs)
and drops any member of that name, in any letter case, that the caller sent.
- Every HTTP answer, including error statuses, is returned as a successful call with `status`
and `data`; check `status`. Only a failure to reach the agent service fails the call.
- Not idempotent: a call can start an agent turn.
## Request: AgentApiV2Request
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `method` | `string` | The HTTP method: GET, POST, PUT, PATCH or DELETE. Empty means POST. |
| `path` | `string` | The API path below the vault, for example `conversations`. Without the API version, the vault or a query string. |
| `parameters` | `string` | The request body, a JSON object, or empty for an empty object. |
| `allow_delegation` | `bool` | True to let the agent service call back to the vault as the session's user. Fails with "Not implemented." on servers that do not support it. |
## Response: AgentApiV2Response
> Nested 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` | `int32` | The HTTP status code that the agent service returned. |
| `data` | `string` | The response body as returned by the agent service; empty when it had none. |
---
# IRPCAgent.CreateAgentResponse
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CreateAgentResponse/
Badges: `Vault API / standard` `write` `session` `idempotent` `returns metadata structure version`
Sends one turn to the general Aino agent and returns its answer. Used by M-Files clients; the
request and response formats are internal to them.
- **Service:** [Aino agents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/index.md) `MFiles.IRPCAgent`
- **gRPC method:** `/MFiles.IRPCAgent/CreateAgentResponse`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-agent-response`
- **Request:** [`CreateAgentResponseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CreateAgentResponse/index.md#request)
- **Response:** [`CreateAgentResponseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAgent/CreateAgentResponse/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session of a user and a vault whose subscription includes Aino.
- The server forwards the request as given and returns the agent's answer unchanged.
## Request: CreateAgentResponseRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `agent_request` | [`AgentRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AgentRequest/index.md) | The request document, in a format internal to the M-Files clients. |
| `agent_request.data` | `string` | The request document, in a format internal to the M-Files clients. |
## Response: CreateAgentResponseResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `agent_response` | [`AgentResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AgentResponse/index.md) | The agent's answer. |
| `agent_response.data` | `string` | The answer document, in a format internal to the M-Files clients. |
---
# Anonymous login (IRPCAnonymousLoginOperations)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/
An interface for managing anonymous authentication operations.
This interface provides ability to enable or disable anonymous authentication.
- **gRPC service:** `MFiles.IRPCAnonymousLoginOperations`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 2
- **Proto file:** [`mfiles/IRPCAnonymousLoginOperations.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCAnonymousLoginOperations.proto)
## Overview
Turns anonymous access to the vault on or off, and tells whether it is on. Used by vault
administration tools; applications that only read or write vault content do not need it.
- [GetAnonymousAuthenticationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/GetAnonymousAuthenticationSettings/index.md)
reads the setting.
- [SetAnonymousAuthenticationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/SetAnonymousAuthenticationSettings/index.md)
changes it.
Both methods need a vault session whose user has the vault rights `manage_users` and
`license_allows_modifications` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); other users get
"Access denied.".
Anonymous access is a user account of the vault: the account `ANONYMOUS LOGON` of the domain
`M-FILES AUTHORITY`. Turning it on creates that account or lets the existing one
log in again; turning it off only stops the account from logging in. What anonymous users may
see is governed by the permissions of that account, like for any other user. When it is on,
clients log in with `AUTH_DATA_TYPE_ANONYMOUS` (see
[Authentication and sessions](https://developer.m-files.com/APIs/gRPC-API/runtime/authentication/index.md)).
Without a session, [GetLoginSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetLoginSettings/index.md) tells whether
a host name allows anonymous login.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetAnonymousAuthenticationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/GetAnonymousAuthenticationSettings/index.md) | Tells whether anonymous access to the vault is turned on. | `write` `session` |
| [SetAnonymousAuthenticationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/SetAnonymousAuthenticationSettings/index.md) | Turns anonymous access to the vault on or off. | `write` `session` |
---
# IRPCAnonymousLoginOperations.GetAnonymousAuthenticationSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Anonymous login](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/GetAnonymousAuthenticationSettings/
Badges: `Vault API / standard` `write` `session`
Tells whether anonymous access to the vault is turned on.
- **Service:** [Anonymous login](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/index.md) `MFiles.IRPCAnonymousLoginOperations`
- **gRPC method:** `/MFiles.IRPCAnonymousLoginOperations/GetAnonymousAuthenticationSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-anonymous-authentication-settings`
- **Request:** [`GetAnonymousAuthenticationSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/GetAnonymousAuthenticationSettings/index.md#request)
- **Response:** [`GetAnonymousAuthenticationSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/GetAnonymousAuthenticationSettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `manage_users` and `license_allows_modifications`.
- Anonymous access counts as on when exactly one anonymous user account exists and it is allowed
to log in.
- Not cacheable: the setting is not covered by the metadata structure version.
## Request: GetAnonymousAuthenticationSettingsRequest
No fields.
## Response: GetAnonymousAuthenticationSettingsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `anonymous_authentication_settings` | [`AnonymousAuthenticationSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AnonymousAuthenticationSettings/index.md) | The current setting. `anonymous_authentication_enabled` is false (unset) when anonymous access is off. |
| `anonymous_authentication_settings.anonymous_authentication_enabled` | `bool` | Boolean indicating whether anonymous authentication should be enabled or disabled. |
---
# IRPCAnonymousLoginOperations.SetAnonymousAuthenticationSettings
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Anonymous login](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/SetAnonymousAuthenticationSettings/
Badges: `Vault API / standard` `write` `session`
Turns anonymous access to the vault on or off.
- **Service:** [Anonymous login](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/index.md) `MFiles.IRPCAnonymousLoginOperations`
- **gRPC method:** `/MFiles.IRPCAnonymousLoginOperations/SetAnonymousAuthenticationSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-anonymous-authentication-settings`
- **Request:** [`SetAnonymousAuthenticationSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/SetAnonymousAuthenticationSettings/index.md#request)
- **Response:** [`SetAnonymousAuthenticationSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCAnonymousLoginOperations/SetAnonymousAuthenticationSettings/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Requires the vault rights `manage_users` and `license_allows_modifications`.
- On: creates the anonymous user account if the vault has none, or allows the existing one to
log in. Off: the account stays but can no longer log in. Calling with the current value
changes nothing.
- If the vault has more than one anonymous user account, the call fails with "Not
implemented.".
- Anyone who can reach the server can then read whatever the anonymous account is allowed to
see. Check its permissions before turning anonymous access on.
## Request: SetAnonymousAuthenticationSettingsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `anonymous_authentication_settings` | [`AnonymousAuthenticationSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AnonymousAuthenticationSettings/index.md) | Set `anonymous_authentication_enabled` to true to turn anonymous access on, false to turn it off. |
| `anonymous_authentication_settings.anonymous_authentication_enabled` | `bool` | Boolean indicating whether anonymous authentication should be enabled or disabled. |
## Response: SetAnonymousAuthenticationSettingsResponse
No fields.
---
# Identities (IRPCIdentityOperations)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/
Lets M-Files cloud services that hand out object and value list item IDs on behalf of a vault
ask the vault to replenish their ID ranges.
- **gRPC service:** `MFiles.IRPCIdentityOperations`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCIdentityOperations.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCIdentityOperations.proto)
## Overview
Infrastructure for M-Files Cloud. Applications do not call this service: it accepts only
technical login accounts of M-Files cloud services, and servers without the feature answer
"Not implemented.".
## Methods
| Method | Summary | Facts |
|---|---|---|
| [RequestIdentityPoolTopUp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/RequestIdentityPoolTopUp/index.md) | Asks the vault to replenish the ID ranges that an M-Files cloud service holds for it. Used by M-Files cloud services only. | `write` `session` `idempotent` |
---
# IRPCIdentityOperations.RequestIdentityPoolTopUp
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Identities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/RequestIdentityPoolTopUp/
Badges: `Vault API / standard` `write` `session` `idempotent`
Asks the vault to replenish the ID ranges that an M-Files cloud service holds for it. Used by
M-Files cloud services only.
- **Service:** [Identities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/index.md) `MFiles.IRPCIdentityOperations`
- **gRPC method:** `/MFiles.IRPCIdentityOperations/RequestIdentityPoolTopUp`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/request-identity-pool-top-up`
- **Request:** [`RequestIdentityPoolTopUpRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/RequestIdentityPoolTopUp/index.md#request)
- **Response:** [`RequestIdentityPoolTopUpResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCIdentityOperations/RequestIdentityPoolTopUp/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
- Returns at once; the vault does the work in the background. Repeated requests are combined,
so the call is safe to retry.
- Requires a vault session with full control of the vault, and the session's account must be
a technical login account of an M-Files cloud service. Other accounts, including vault
administrators, get "Access denied.".
- Fails with "Not implemented." on servers and vaults where the feature is not available.
## Request: RequestIdentityPoolTopUpRequest
No fields.
## Response: RequestIdentityPoolTopUpResponse
No fields.
---
# Extension authentications (IRPCExtensionAuthentications)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/
Manages the credentials that the vault uses to access external systems, such as external
repositories connected to the vault, on behalf of the user.
- **gRPC service:** `MFiles.IRPCExtensionAuthentications`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 8
- **Proto file:** [`mfiles/IRPCExtensionAuthentications.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCExtensionAuthentications.proto)
## Overview
Some vault applications and external repository connections need the user's own credentials
for the external system. The server keeps those credentials per user and target. M-Files
clients use this service in their "external repositories" dialogs.
1. [GetExtensionAuthenticationTargets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets/index.md)
lists the external systems (targets) and the authentication methods they accept.
2. [GetExtensionAuthenticationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus/index.md)
tells for which targets the caller has stored credentials.
3. [StoreExtensionAuthenticationCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/index.md)
logs the caller in to a target by storing credentials.
4. [LogoutWithExtensionAuthentication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogoutWithExtensionAuthentication/index.md)
removes them.
All methods need a vault session; anonymous sessions cannot store credentials. A target is
identified by `ExtensionAuthenticationTarget.id`. Methods that name an unknown target generally
succeed without doing anything, so check the result with
[GetExtensionAuthenticationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus/index.md).
Credentials for the whole vault (common, background and permission-reading accounts) are set
by vault administrators with
[StoreExtensionAuthenticationSpecialCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationSpecialCredentials/index.md).
Send credentials only over TLS.
## Methods
| Method | Summary | Facts |
|---|---|---|
| [GetExtensionAuthenticationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus/index.md) | Lists the targets for which the caller has stored credentials, with the account name used. | `read` `session` `idempotent` `returns metadata structure version` |
| [GetExtensionAuthenticationTargets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets/index.md) | Lists the external systems that accept credentials through this service. | `read` `session` `idempotent` `returns metadata structure version` |
| [LogInAsDifferentUserForExtensionAuthentication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogInAsDifferentUserForExtensionAuthentication/index.md) | Asks the external system to start a new login for the caller, so that the caller can switch to another account there. Used by M-Files clients; applications rarely call it. | `write` `session` `returns metadata structure version` |
| [LoginWithExtensionAuthentication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication/index.md) | Logs the caller in to an external system with encrypted credentials. | `write` `session` `returns metadata structure version` |
| [LogoutWithExtensionAuthentication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogoutWithExtensionAuthentication/index.md) | Removes the caller's stored credentials for an external system and logs the caller out of it. | `write` `session` `returns metadata structure version` |
| [RemoveExtensionAuthenticationSpecialCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/RemoveExtensionAuthenticationSpecialCredentials/index.md) | Removes vault-wide credentials for an external system. Used by vault administration tools. | `write` `session` `returns metadata structure version` |
| [StoreExtensionAuthenticationCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/index.md) | Logs the caller in to an external system by storing the caller's credentials for it. | `write` `session` `returns metadata structure version` |
| [StoreExtensionAuthenticationSpecialCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationSpecialCredentials/index.md) | Stores vault-wide credentials for an external system: the common, background or permission-reading account. Used by vault administration tools. | `write` `session` `returns metadata structure version` |
---
# IRPCExtensionAuthentications.GetExtensionAuthenticationStatus
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Lists the targets for which the caller has stored credentials, with the account name used.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-extension-authentication-status`
- **Request:** [`GetExtensionAuthenticationStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus/index.md#request)
- **Response:** [`GetExtensionAuthenticationStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationStatus/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. Returns only the caller's own entries.
- A target with no entry has no stored credentials for the caller.
## Request: GetExtensionAuthenticationStatusRequest
No fields.
## Response: GetExtensionAuthenticationStatusResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `statuses[]` | repeated [`ExtensionAuthenticationStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtensionAuthenticationStatus/index.md) | One entry per target with stored credentials. |
| `statuses[].user` | `int32` | The ID of the user account the credentials belong to. |
| `statuses[].user_type` | [`ExtensionAuthenticationSpecialUserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtensionAuthenticationSpecialUserType/index.md) | `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_NORMAL` for a user's own credentials, or the kind of vault-wide account. Values: `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_NORMAL` (0), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_COMMON` (1), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_BACKGROUND` (2), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_PERMISSIONS` (3). |
| `statuses[].connection_name` | `string` | The `id` of the target. |
| `statuses[].account` | `string` | The account name on the external system. |
| `statuses[].is_missing` | `bool` | True if no usable credentials are stored for this user and target. |
---
# IRPCExtensionAuthentications.GetExtensionAuthenticationTargets
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Lists the external systems that accept credentials through this service.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-extension-authentication-targets`
- **Request:** [`GetExtensionAuthenticationTargetsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets/index.md#request)
- **Response:** [`GetExtensionAuthenticationTargetsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
- Requires a vault session. No special vault rights are needed.
- Empty when the vault has no external system that accepts credentials this way.
## Request: GetExtensionAuthenticationTargetsRequest
No fields.
## Response: GetExtensionAuthenticationTargetsResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `targets[]` | repeated [`ExtensionAuthenticationTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtensionAuthenticationTarget/index.md) | The targets. Pass `id` as `target` to the other methods, and use `supported_plugins` to choose how to authenticate. |
| `targets[].id` | `string` | The identifier of the target. Pass it as `target` to the other methods of [IRPCExtensionAuthentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md). |
| `targets[].name` | `string` | The display name of the target. |
| `targets[].icon_id` | `string` | An identifier of the target's icon. |
| `targets[].requires_user_specific_authentication` | `bool` | True if each user must store their own credentials for this target. |
| `targets[].supported_plugins[]` | repeated [`PluginInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PluginInfo/index.md) | The authentication methods the target accepts. The `name` of the chosen one goes to `ExtensionAuthenticationResponse.plugin_configuration`. |
| `targets[].supported_plugins[].is_default` | `bool` | True if this is the default configuration. |
| `targets[].supported_plugins[].is_scope_independent` | `bool` | True if the plug-in can be used without a configuration scope. |
| `targets[].supported_plugins[].name` | `string` | The configuration's name. Send it as `PluginData.plugin_name`. |
| `targets[].supported_plugins[].assembly_name` | `string` | The plug-in's implementation, for example `MFiles.AuthenticationProviders.OAuth`. |
| `targets[].supported_plugins[].bridge_class_name` | `string` | Internal to the server. |
| `targets[].supported_plugins[].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`. |
| `targets[].supported_plugins[].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`. |
---
# IRPCExtensionAuthentications.LogInAsDifferentUserForExtensionAuthentication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogInAsDifferentUserForExtensionAuthentication/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Asks the external system to start a new login for the caller, so that the caller can switch to
another account there. Used by M-Files clients; applications rarely call it.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/LogInAsDifferentUserForExtensionAuthentication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/log-in-as-different-user-for-extension-authentication`
- **Request:** [`LogInAsDifferentUserForExtensionAuthenticationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogInAsDifferentUserForExtensionAuthentication/index.md#request)
- **Response:** [`LogInAsDifferentUserForExtensionAuthenticationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogInAsDifferentUserForExtensionAuthentication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session of a user; anonymous sessions fail.
- What happens depends on the external system; any new credentials are stored for the caller.
## Request: LogInAsDifferentUserForExtensionAuthenticationRequest
> Nested 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` | `string` | The `id` of the target. |
## Response: LogInAsDifferentUserForExtensionAuthenticationResponse
No fields.
---
# IRPCExtensionAuthentications.LoginWithExtensionAuthentication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Logs the caller in to an external system with encrypted credentials. Used by M-Files clients
that encrypt the credentials above the transport layer; applications should call
[StoreExtensionAuthenticationCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/index.md)
over TLS instead.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/login-with-extension-authentication`
- **Request:** [`LoginWithExtensionAuthenticationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication/index.md#request)
- **Response:** [`LoginWithExtensionAuthenticationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Data that the server cannot decrypt fails with "The parameter is incorrect.".
## Request: LoginWithExtensionAuthenticationRequest
> Nested 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` | `string` | The `id` of the target. |
| `ear_data_encrypted` | `bytes` | The credentials, encrypted with the server's public key in a format internal to the M-Files clients. |
## Response: LoginWithExtensionAuthenticationResponse
No fields.
## Related methods
- [StoreExtensionAuthenticationCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/index.md): Logs the caller in to an external system by storing the caller's credentials for it.
---
# IRPCExtensionAuthentications.LogoutWithExtensionAuthentication
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogoutWithExtensionAuthentication/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Removes the caller's stored credentials for an external system and logs the caller out of it.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/LogoutWithExtensionAuthentication`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/logout-with-extension-authentication`
- **Request:** [`LogoutWithExtensionAuthenticationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogoutWithExtensionAuthentication/index.md#request)
- **Response:** [`LogoutWithExtensionAuthenticationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LogoutWithExtensionAuthentication/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session. Affects only the caller's own credentials.
- Succeeds also when nothing was stored for the target.
## Request: LogoutWithExtensionAuthenticationRequest
> Nested 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` | `string` | The `id` of the target. |
## Response: LogoutWithExtensionAuthenticationResponse
No fields.
---
# IRPCExtensionAuthentications.RemoveExtensionAuthenticationSpecialCredentials
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/RemoveExtensionAuthenticationSpecialCredentials/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Removes vault-wide credentials for an external system. Used by vault administration tools.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/RemoveExtensionAuthenticationSpecialCredentials`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-extension-authentication-special-credentials`
- **Request:** [`RemoveExtensionAuthenticationSpecialCredentialsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/RemoveExtensionAuthenticationSpecialCredentials/index.md#request)
- **Response:** [`RemoveExtensionAuthenticationSpecialCredentialsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/RemoveExtensionAuthenticationSpecialCredentials/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires full control of the vault; other users get "Access denied.".
- Succeeds also when nothing was stored.
## Request: RemoveExtensionAuthenticationSpecialCredentialsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `eeasut` | [`ExtensionAuthenticationSpecialUserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtensionAuthenticationSpecialUserType/index.md) | Which vault-wide account to remove. Values: `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_NORMAL` (0), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_COMMON` (1), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_BACKGROUND` (2), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_PERMISSIONS` (3). |
| `target` | `string` | The `id` of the target. |
## Response: RemoveExtensionAuthenticationSpecialCredentialsResponse
No fields.
---
# IRPCExtensionAuthentications.StoreExtensionAuthenticationCredentials
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Logs the caller in to an external system by storing the caller's credentials for it.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/store-extension-authentication-credentials`
- **Request:** [`StoreExtensionAuthenticationCredentialsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/index.md#request)
- **Response:** [`StoreExtensionAuthenticationCredentialsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationCredentials/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires a vault session of a user; anonymous sessions fail. `target` must not be empty
("The parameter is incorrect. (Invalid target name.)").
- Replaces credentials already stored for the caller and the target.
- The credentials travel in clear text inside the message. Use this method only over TLS.
- Use this method rather than
[LoginWithExtensionAuthentication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication/index.md),
which expects encrypted data.
## Request: StoreExtensionAuthenticationCredentialsRequest
> Nested 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` | `string` | The `id` of the target, from [GetExtensionAuthenticationTargets](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/GetExtensionAuthenticationTargets/index.md). |
| `authentication_data` | [`ExtensionAuthenticationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtensionAuthenticationResponse/index.md) | The credentials. See [ExtensionAuthenticationResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtensionAuthenticationResponse/index.md). |
| `authentication_data.plugin_configuration` | `string` | The `name` of the authentication method, from the target's `supported_plugins`. |
| `authentication_data.data[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | The credentials as named text values, as the authentication method expects them. For a user name and password, M-Files clients send `username` and `password`; for tokens, `Token` and `RefreshToken`. |
| `authentication_data.data[].key` | `string` | The name of the value. |
| `authentication_data.data[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The value as a serialized bytearray. |
## Response: StoreExtensionAuthenticationCredentialsResponse
No fields.
## Related methods
- [LoginWithExtensionAuthentication](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/LoginWithExtensionAuthentication/index.md): Logs the caller in to an external system with encrypted credentials.
---
# IRPCExtensionAuthentications.StoreExtensionAuthenticationSpecialCredentials
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationSpecialCredentials/
Badges: `Vault API / standard` `write` `session` `returns metadata structure version`
Stores vault-wide credentials for an external system: the common, background or
permission-reading account. Used by vault administration tools.
- **Service:** [Extension authentications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/index.md) `MFiles.IRPCExtensionAuthentications`
- **gRPC method:** `/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationSpecialCredentials`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/store-extension-authentication-special-credentials`
- **Request:** [`StoreExtensionAuthenticationSpecialCredentialsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationSpecialCredentials/index.md#request)
- **Response:** [`StoreExtensionAuthenticationSpecialCredentialsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExtensionAuthentications/StoreExtensionAuthenticationSpecialCredentials/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **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)
## Remarks
- Requires full control of the vault; other users get "Access denied.".
- The credentials must be encrypted in a format internal to the M-Files clients; data that the
server cannot decrypt fails with "The parameter is incorrect.".
## Request: StoreExtensionAuthenticationSpecialCredentialsRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `eeasut` | [`ExtensionAuthenticationSpecialUserType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtensionAuthenticationSpecialUserType/index.md) | Which vault-wide account to set: `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_COMMON`, `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_BACKGROUND` or `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_PERMISSIONS`. Values: `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_NORMAL` (0), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_COMMON` (1), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_BACKGROUND` (2), `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_PERMISSIONS` (3). |
| `target` | `string` | The `id` of the target. |
| `ear_data_encrypted` | `bytes` | The credentials, encrypted with the server's public key in a format internal to the M-Files clients. |
## Response: StoreExtensionAuthenticationSpecialCredentialsResponse
No fields.
---
# Connection and health checks (IRPCTest)
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/
An interface for testing connection between a client and the server.
This interface offers simple methods to test if a connection is valid,
either to the server (without a need to login) or to a specific vault
(requires login).
- **gRPC service:** `MFiles.IRPCTest`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), standard
- **Methods:** 9
- **Proto file:** [`mfiles/IRPCTest.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCTest.proto)
## Overview
Connectivity, throughput and health checks. Each method checks one thing and returns; none of them
reads or changes objects or metadata, and several need no session at all.
| Job | Methods | Session |
|---|---|---|
| Round-trip time to the server | `TestConnectionToServer` | None |
| Is the vault session still valid? | `TestConnectionToVault` | Vault |
| Download and upload throughput | `DownloadTestFile_Begin`, `UploadTestFile_Begin` | Vault |
| Is a vault ready? (load balancers) | `CheckVaultHealthAnonymous`, `TestVaultAvailability` | None |
| Is the server ready? | `CheckServerHealthAnonymous` | None |
| Which server check fails? | `GetServerHealth` | Any |
| Connection from this server to another | `TestConnectionToRemoteServer` | None |
Where another service is the better choice:
- To find out whether the server answers and which version it runs, call
[QueryVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md). It needs no session either and is
the usual first call of a client. Use `TestConnectionToServer` when you want to time repeated
round trips with an empty request and response.
- To keep a session from expiring, call [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md).
`TestConnectionToVault` checks the session but does not extend its lifetime.
Errors follow the usual pattern: a missing, invalid or logged-out session is reported as gRPC
status `UNAUTHENTICATED` without error trailers, and every other failure as `UNKNOWN` with the
M-Files error stack in the `mfiles-error-serialized-bin` trailer. See
[Errors](https://developer.m-files.com/APIs/gRPC-API/runtime/errors/index.md) and
[Connecting to the server](https://developer.m-files.com/APIs/gRPC-API/runtime/connecting/index.md).
## Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| [TestConnectionToServer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToServer/index.md) | Does nothing and returns at once. Use it to check that calls reach the server and to measure the round-trip time. | `write` `no session` |
| [TestConnectionToVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToVault/index.md) | Checks that the session is a valid vault session, and does nothing else. | `write` `session` `idempotent` |
| [CheckVaultHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md) | Succeeds when a vault on this server is ready for use; fails otherwise. No session needed. Made for load balancer health probes. | `read` `no session` `idempotent` |
| [DownloadTestFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/DownloadTestFile_Begin/index.md) | Creates a file of random bytes on the server and opens a download session for it, for measuring download throughput. | `read` `session` `idempotent` `returns metadata structure version` |
## Other methods
| Method | Summary | Facts |
|---|---|---|
| [CheckServerHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckServerHealthAnonymous/index.md) | Succeeds when the server and all its vaults have finished starting; fails otherwise. No session needed. | `read` `no session` `idempotent` |
| [GetServerHealth](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/GetServerHealth/index.md) | Runs the server health checks you select and returns the result of each. | `read` `session` `idempotent` |
| [TestConnectionToRemoteServer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToRemoteServer/index.md) | Asks this server to connect to another M-Files Server and call `TestConnectionToServer` there. Normally disabled. | `write` `no session` |
| [TestVaultAvailability](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestVaultAvailability/index.md) | Checks that a vault on this server is online and that its database and file data storage can be accessed. No session needed. | `write` `no session` |
| [UploadTestFile_Begin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/UploadTestFile_Begin/index.md) | Starts an upload whose bytes the server discards, for measuring upload throughput. | `write` `session` `idempotent` |
---
# IRPCTest.TestConnectionToServer
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToServer/
Badges: `Vault API / standard` `write` `no session`
Does nothing and returns at once. Use it to check that calls reach the server and to measure the
round-trip time.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/TestConnectionToServer`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/test-connection-to-server`
- **Request:** [`TestConnectionToServerRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToServer/index.md#request)
- **Response:** [`TestConnectionToServerResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToServer/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session; an `mfiles-session-id-bin` header, if sent, is ignored. The request and the
response are empty, so the time a call takes is the network round trip plus the server's minimal
call overhead.
The first call on a new channel also includes setting up the connection (on a local server, about
18 ms against about 1 ms for the calls after it), so leave it out of round-trip measurements.
## Request: TestConnectionToServerRequest
No fields.
## Response: TestConnectionToServerResponse
No fields.
---
# IRPCTest.TestConnectionToVault
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToVault/
Badges: `Vault API / standard` `write` `session` `idempotent`
Checks that the session is a valid vault session, and does nothing else.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/TestConnectionToVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/test-connection-to-vault`
- **Request:** [`TestConnectionToVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToVault/index.md#request)
- **Response:** [`TestConnectionToVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToVault/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Send the session in `mfiles-session-id-bin`. The call succeeds with an empty response while the
session is valid. A missing, unknown or logged-out session fails with `UNAUTHENTICATED`.
A server-level session (opened with the all-zero vault GUID) fails with `E_MFILES_LOGIN_REQUIRED`
("Login required.").
This is the cheapest way to find out whether a session is still usable before a batch of work, and
to measure the round-trip time of authenticated vault calls. It does not reset the session's idle
timer: keep the session open with [KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md).
## Request: TestConnectionToVaultRequest
No fields.
## Response: TestConnectionToVaultResponse
No fields.
## Related methods
- [IRPCLogin.KeepAlive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/KeepAlive/index.md): Tells the server that the session is still in use, so that it does not expire.
---
# IRPCTest.CheckVaultHealthAnonymous
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/
Badges: `Vault API / standard` `read` `no session` `idempotent`
Succeeds when a vault on this server is ready for use; fails otherwise. No session needed. Made for
load balancer health probes.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/CheckVaultHealthAnonymous`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-vault-health-anonymous`
- **Request:** [`CheckVaultHealthAnonymousRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md#request)
- **Response:** [`CheckVaultHealthAnonymousResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. The call succeeds with an empty response when the vault is fully online, its
database can be read and its file data storage can be accessed. A load balancer in front of
several servers that host the same vault can call it on each server and route traffic only to the
servers that answer successfully.
Any failed check, including a vault that is offline or still starting, fails with
`E_MFILES_VAULT_CANT_BE_USED_RIGHT_NOW` ("The vault can't be used right now.") without further
details. An unknown vault GUID, an empty string and the all-zero GUID fail with
`E_MFILES_UNKNOWN_VAULT` ("The specified document vault does not exist."); a malformed GUID fails
with `E_INVALIDARG` ("The parameter is incorrect.").
Compared with [TestVaultAvailability](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestVaultAvailability/index.md), this method
always treats a vault that is not ready as a failure and never reveals why it failed.
## Request: CheckVaultHealthAnonymousRequest
> Nested 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 or without braces, in any case. |
## Response: CheckVaultHealthAnonymousResponse
No fields.
## Related methods
- [TestVaultAvailability](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestVaultAvailability/index.md): Checks that a vault on this server is online and that its database and file data storage can be accessed. No session needed.
---
# IRPCTest.DownloadTestFile_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/DownloadTestFile_Begin/
Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`
Creates a file of random bytes on the server and opens a download session for it, for measuring
download throughput.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/DownloadTestFile_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-test-file_-begin`
- **Request:** [`DownloadTestFile_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/DownloadTestFile_Begin/index.md#request)
- **Response:** [`DownloadTestFile_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/DownloadTestFile_Begin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)
## Remarks
Needs a vault session. Without a session the call fails with `UNAUTHENTICATED`; a server-level
session fails with `E_MFILES_LOGIN_REQUIRED`. `file_size` must be from 0 to 52428800 (50 MiB);
other values fail with `E_INVALIDARG` ("The parameter is incorrect.").
The server writes `file_size` random bytes to a temporary file of the vault; the content differs
on every call and does not compress. Read it like any other download:
1. Call this method and keep `download_id`.
2. Read the blocks with
[DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md), at most
4 MiB per call, and time those calls. Creating the file is part of this method, not of the
reads (on a local server, `DownloadTestFile_Begin` for 50 MiB took about 200 ms).
3. Close the session with
[DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md). When the file was read
in order and the last read returned fewer bytes than requested, the server has already closed
the session; `DownloadFile_Stop` still succeeds.
The response carries only `download_id`.
## Request: DownloadTestFile_BeginRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_size` | `int64` | The size of the test file in bytes, 0 to 52428800 (50 MiB). |
## Response: DownloadTestFile_BeginResponse
> Nested 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 for `DownloadFile_ReadBlock` and `DownloadFile_Stop`. Valid only with the session that started it. |
## Related methods
- [IRPCObjectOperations.DownloadFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_ReadBlock/index.md): Reads a block of a file from a download session.
- [IRPCObjectOperations.DownloadFile_Stop](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/DownloadFile_Stop/index.md): Closes a download session.
---
# IRPCTest.CheckServerHealthAnonymous
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckServerHealthAnonymous/
Badges: `Vault API / standard` `read` `no session` `idempotent`
Succeeds when the server and all its vaults have finished starting; fails otherwise. No session
needed.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/CheckServerHealthAnonymous`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-server-health-anonymous`
- **Request:** [`CheckServerHealthAnonymousRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckServerHealthAnonymous/index.md#request)
- **Response:** [`CheckServerHealthAnonymousResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckServerHealthAnonymous/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. The call succeeds with an empty response when all of these hold:
- Every vault has finished going online.
- Every vault that is set to be online is online.
- On servers that load their vaults from One DB, the latest refresh from One DB succeeded.
Otherwise it fails with `E_FAIL` and no details. Use it as a readiness probe for the whole server,
for example after a restart. To see which check fails, call
[GetServerHealth](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/GetServerHealth/index.md) with a session; to probe one vault, use
[CheckVaultHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md).
## Request: CheckServerHealthAnonymousRequest
No fields.
## Response: CheckServerHealthAnonymousResponse
No fields.
## Related methods
- [GetServerHealth](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/GetServerHealth/index.md): Runs the server health checks you select and returns the result of each.
- [CheckVaultHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md): Succeeds when a vault on this server is ready for use; fails otherwise. No session needed. Made for load balancer health probes.
---
# IRPCTest.GetServerHealth
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/GetServerHealth/
Badges: `Vault API / standard` `read` `session` `idempotent`
Runs the server health checks you select and returns the result of each.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/GetServerHealth`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-health`
- **Request:** [`GetServerHealthRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/GetServerHealth/index.md#request)
- **Response:** [`GetServerHealthResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/GetServerHealth/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs a session. Without a session the call fails with `UNAUTHENTICATED`.
These are the checks of
[CheckServerHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckServerHealthAnonymous/index.md), selected one by one
in `data_request`:
- `vault_refresh_from_one_db`: the latest refresh of the vault list from One DB succeeded.
- `online_state_transition_finished_for_all_vaults`: every vault has finished going online.
- `all_vaults_in_correct_end_state`: every vault that is set to be online is online.
Each of them is a `ServerHealthItem`:
- `SERVER_HEALTH_ITEM_IGNORE` (the default): the check is not run and its result field stays
`TRI_STATE_BOOLEAN_UNDEFINED`. An empty request therefore returns an empty result.
- `SERVER_HEALTH_ITEM_CHECK`: the check is run and its result field is `TRI_STATE_BOOLEAN_TRUE` or
`TRI_STATE_BOOLEAN_FALSE`.
- `SERVER_HEALTH_ITEM_FAIL_IF_UNHEALTHY`: the check is run, and the call fails instead of
returning `TRI_STATE_BOOLEAN_FALSE`.
A vault that has not finished going online counts as unhealthy for both vault checks.
## Request: GetServerHealthRequest
> Nested 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_request` | [`ServerHealthRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerHealthRequest/index.md) | Which checks to run, and whether a failed check fails the call; see Remarks. |
| `data_request.vault_refresh_from_one_db` | [`ServerHealthItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerHealthItem/index.md) | Check that a refresh from One DB has been successfully made. Values: `SERVER_HEALTH_ITEM_IGNORE` (0), `SERVER_HEALTH_ITEM_CHECK` (1), `SERVER_HEALTH_ITEM_FAIL_IF_UNHEALTHY` (2). |
| `data_request.online_state_transition_finished_for_all_vaults` | [`ServerHealthItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerHealthItem/index.md) | Check that all the vaults have finished the online transition. Values: `SERVER_HEALTH_ITEM_IGNORE` (0), `SERVER_HEALTH_ITEM_CHECK` (1), `SERVER_HEALTH_ITEM_FAIL_IF_UNHEALTHY` (2). |
| `data_request.all_vaults_in_correct_end_state` | [`ServerHealthItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ServerHealthItem/index.md) | Check that all the vaults are in correct end state. Values: `SERVER_HEALTH_ITEM_IGNORE` (0), `SERVER_HEALTH_ITEM_CHECK` (1), `SERVER_HEALTH_ITEM_FAIL_IF_UNHEALTHY` (2). |
## Response: GetServerHealthResponse
> Nested 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_result` | [`ServerHealthResult`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerHealthResult/index.md) | One result per check. A check that was not requested is `TRI_STATE_BOOLEAN_UNDEFINED`. `vault_refresh_from_one_db_succeeded` is also `TRI_STATE_BOOLEAN_UNDEFINED` on servers that do not use One DB, which is the normal case on premises. |
| `data_result.vault_refresh_from_one_db_succeeded` | [`TriStateBoolean`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TriStateBoolean/index.md) | True, if a refresh from One DB has been successfully made. Undefined, if One DB is not enabled for the server. Values: `TRI_STATE_BOOLEAN_UNDEFINED` (0), `TRI_STATE_BOOLEAN_FALSE` (1), `TRI_STATE_BOOLEAN_TRUE` (2). |
| `data_result.online_state_transition_finished_for_all_vaults_succeeded` | [`TriStateBoolean`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TriStateBoolean/index.md) | True, if all the vaults have finished the online transition. Values: `TRI_STATE_BOOLEAN_UNDEFINED` (0), `TRI_STATE_BOOLEAN_FALSE` (1), `TRI_STATE_BOOLEAN_TRUE` (2). |
| `data_result.all_vaults_in_correct_end_state_succeeded` | [`TriStateBoolean`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TriStateBoolean/index.md) | True, if all the vaults are in correct end state. Values: `TRI_STATE_BOOLEAN_UNDEFINED` (0), `TRI_STATE_BOOLEAN_FALSE` (1), `TRI_STATE_BOOLEAN_TRUE` (2). |
## Related methods
- [CheckServerHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckServerHealthAnonymous/index.md): Succeeds when the server and all its vaults have finished starting; fails otherwise. No session needed.
---
# IRPCTest.TestConnectionToRemoteServer
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToRemoteServer/
Badges: `Vault API / standard` `write` `no session`
Asks this server to connect to another M-Files Server and call `TestConnectionToServer` there.
Normally disabled.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/TestConnectionToRemoteServer`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/test-connection-to-remote-server`
- **Request:** [`TestConnectionToRemoteServerRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToRemoteServer/index.md#request)
- **Response:** [`TestConnectionToRemoteServerResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToRemoteServer/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session. Unless the server enables cached replica connections, which is normally
disabled, the call fails with `E_MFILES_CONFIGURING_REPLICA_VAULTS_NOT_ALLOWED` ("M-Files no
longer supports the creation of replica vaults."). That check comes first, so the server makes no
connection in that case. Applications have no use for this method; to test your own connection to
a server, call [TestConnectionToServer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToServer/index.md) on that
server.
## Request: TestConnectionToRemoteServerRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `remote` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The MS-RPC address of the other server. Used only where the feature is enabled. |
| `remote.network_address` | `string` | The network address (name) of the server. |
| `remote.endpoint` | `string` | The endpoint of the server. |
| `remote.protocol_sequence` | `string` | The protocol sequence of the server. |
## Response: TestConnectionToRemoteServerResponse
No fields.
## Related methods
- [TestConnectionToServer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestConnectionToServer/index.md): Does nothing and returns at once. Use it to check that calls reach the server and to measure the round-trip time.
---
# IRPCTest.TestVaultAvailability
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestVaultAvailability/
Badges: `Vault API / standard` `write` `no session`
Checks that a vault on this server is online and that its database and file data storage can be
accessed. No session needed.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/TestVaultAvailability`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/test-vault-availability`
- **Request:** [`TestVaultAvailabilityRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestVaultAvailability/index.md#request)
- **Response:** [`TestVaultAvailabilityResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/TestVaultAvailability/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs no session; an `mfiles-session-id-bin` header, if sent, is ignored. The call succeeds with an
empty response when the vault passes the checks.
When the vault is fully online, the server checks that the vault database and the vault's file
data storage can be accessed. A failed check returns the error code of the failure, with any
details replaced by `********`.
When the vault is not fully online, or the server is shutting down, the result depends on
`check_online_status`:
- `false`: the call succeeds without checking anything. Use this when an offline vault is not an
error for you.
- `true`: the call fails with `E_MFILES_SHUTDOWN_IN_PROGRESS`, `E_MFILES_VAULT_OFFLINE`,
`E_MFILES_VAULT_GOING_OFFLINE` or `E_MFILES_VAULT_NOT_READY` (the vault is still starting).
The exception is a vault taken offline by its scheduled optimization job: the call succeeds.
An unknown vault GUID fails with `E_MFILES_UNKNOWN_VAULT` ("The specified document vault does not
exist.", with the detail `Vault ID: `) whatever `check_online_status` is. An empty string
counts as the all-zero GUID and fails the same way; a malformed GUID fails with `E_INVALIDARG`
("The parameter is incorrect.").
For a load balancer probe, prefer
[CheckVaultHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md), which is made for
that purpose.
## Request: TestVaultAvailabilityRequest
> Nested 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 vault GUID, with or without braces, in any case. |
| `check_online_status` | `bool` | `true` to fail when the vault is not fully online; `false` to succeed without checks in that case. |
## Response: TestVaultAvailabilityResponse
No fields.
## Related methods
- [CheckVaultHealthAnonymous](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/CheckVaultHealthAnonymous/index.md): Succeeds when a vault on this server is ready for use; fails otherwise. No session needed. Made for load balancer health probes.
---
# IRPCTest.UploadTestFile_Begin
Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md)
HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/UploadTestFile_Begin/
Badges: `Vault API / standard` `write` `session` `idempotent`
Starts an upload whose bytes the server discards, for measuring upload throughput.
- **Service:** [Connection and health checks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/index.md) `MFiles.IRPCTest`
- **gRPC method:** `/MFiles.IRPCTest/UploadTestFile_Begin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-test-file_-begin`
- **Request:** [`UploadTestFile_BeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/UploadTestFile_Begin/index.md#request)
- **Response:** [`UploadTestFile_BeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCTest/UploadTestFile_Begin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)
## Remarks
Needs a vault session. Without a session the call fails with `UNAUTHENTICATED`; a server-level
session fails with `E_MFILES_LOGIN_REQUIRED`.
The response's `upload_id` is always -1, which tells the upload methods to accept the bytes and
store nothing. Nothing is created, so there is nothing to clean up:
1. Call this method; it returns `upload_id` -1.
2. Send the blocks with
[UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md), each with `upload_id` -1,
`total_size_in_bytes` and the `offset` of the block, and time those calls. Each call succeeds
and returns `upload_id` 0; keep using -1.
3. Optionally finish with
[UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md) with
`upload_id` -1, as a real upload would.
Use the block size your application uses for real uploads, so that the measurement matches.
## Request: UploadTestFile_BeginRequest
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `file_size` | `int64` | The planned size of the test upload. |
## Response: UploadTestFile_BeginResponse
> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | Always -1. Pass it to `UploadTempFile` and `UploadTempFileCommit`. |
## Related methods
- [IRPCObjectOperations.UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
- [IRPCObjectOperations.UploadTempFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFileCommit/index.md): Completes an upload made with UploadTempFile.