// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";
import "mfiles/enums.proto";
import "mfiles/structs.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Adds, reads, modifies and removes the user accounts of a vault: who may use the vault, with
// which vault roles.
//
// Use this interface to add, modify and delete user accounts in a vault.
//
// A user account is always associated with a login. The login defines
// the authentication type and password (if not a Windows login). The
// user account in a vault just grants a login access to that vault
// and specifies the vault-level roles of the user. The user account
// has an ID that remains constant and is used to identify the user in
// the database (such as 'Last modified by' entry of document). The
// user account can be associated with a different login without changing
// the user ID in the vault.
//
// Use the IRPCLoginsAdmin and/or IRPCVaultLoginsAdmin interface to manage logins.
//
// M-Files Admin uses this service for the Users node of a vault; administration scripts can use it
// to provision users. All methods need a vault session whose user has the vault right
// `manage_users` ([VaultAccess](mfiles:MFiles.VaultAccess)); the write methods also need
// `license_allows_modifications`. The vault role full control (and a system administrator's
// `full_control_of_vaults`) grants both.
//
// **Login accounts and user accounts.** M-Files separates *who can authenticate* from *who may use
// a vault*:
//
// | Account | Stored in | Managed with | What it holds |
// | --- | --- | --- | --- |
// | Server login account | The server | [IRPCLoginsAdmin](mfiles:MFiles.IRPCLoginsAdmin) | [Login](mfiles:MFiles.Login): account type (M-Files or Windows), user name, password, server roles, license type, full name, email. One login can be used in every vault of the server. |
// | Vault login account | One vault | [IRPCVaultLoginsAdmin](mfiles:MFiles.IRPCVaultLoginsAdmin) | The same [Login](mfiles:MFiles.Login) message, valid for that vault only. Exists only on servers with vault login accounts enabled, such as M-Files Cloud. |
// | User account | One vault | This service | [UserAccount](mfiles:MFiles.UserAccount): the vault user ID, the login it belongs to (`login_name`) and the vault roles. |
//
// - A login authenticates; a user account grants that login access to one vault. A login without a
//   user account in the vault cannot open the vault.
// - `UserAccount.login_name` is the login's account name: the user name of an M-Files login
//   (`MikeT`) or the down-level logon name of a Windows login (domain and user name separated by a
//   backslash).
// - The user ID never changes. Objects refer to it (Created by, Last modified by, permissions), so
//   pointing a user account to another login keeps all references.
// - Managing server login accounts needs the system administrator server role (server right
//   `manage_logins`); managing user accounts and vault login accounts needs only the vault right
//   `manage_users`.
//
// **Methods by task:**
//
// - **Read:** [GetUsers](mfiles:MFiles.IRPCUsersAdmin.GetUsers),
//   [GetUser](mfiles:MFiles.IRPCUsersAdmin.GetUser),
//   [SearchForUser](mfiles:MFiles.IRPCUsersAdmin.SearchForUser) (by login name).
// - **Add or bring back:** [AddUser](mfiles:MFiles.IRPCUsersAdmin.AddUser) (preferred),
//   [AddOrUndeleteUser](mfiles:MFiles.IRPCUsersAdmin.AddOrUndeleteUser),
//   [UndeleteUserByGUID](mfiles:MFiles.IRPCUsersAdmin.UndeleteUserByGUID).
// - **Change and remove:** [ModifyUser](mfiles:MFiles.IRPCUsersAdmin.ModifyUser),
//   [RemoveUser](mfiles:MFiles.IRPCUsersAdmin.RemoveUser).
// - **Follow changes:** [GetChangedUserAccounts](mfiles:MFiles.IRPCUsersAdmin.GetChangedUserAccounts).
//
// Typical provisioning: make sure the login exists (server or vault login), then
// [AddUser](mfiles:MFiles.IRPCUsersAdmin.AddUser) with `login_name` set to the login's account
// name, then add the user to groups with
// [AddMemberToUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddMemberToUserGroup).
//
// Users who lack `manage_users` read users and groups through
// [IRPCVault](mfiles:MFiles.IRPCVault), for example
// [GetUsersAndUserGroups](mfiles:MFiles.IRPCVault.GetUsersAndUserGroups) and
// [GetUserGroups](mfiles:MFiles.IRPCVault.GetUserGroups).
//
// **Accounts with an External ID.** `UserAccount.external_id` links the account to an identity in
// an external system such as Microsoft Entra; identity synchronization (M-Files Manage) maintains
// it. These methods cannot change it, and removing such an account can fail with "Access denied"
// ("... should be deleted via Manage").
service IRPCUsersAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Users" };

	// Gets all user accounts of the vault.
	//
	// - Requires a vault session with the vault right `manage_users`; otherwise fails with "Access
	//   denied.".
	// - Returns existing accounts only; removed users are not included. The order is not specified.
	rpc GetUsers( GetUsersRequest ) returns ( GetUsersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Replaces the data of an existing user account.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`. Adding or
	//   removing the `full_control` role also requires `change_full_control_role`.
	// - Send the complete account: read it with [GetUser](mfiles:MFiles.IRPCUsersAdmin.GetUser),
	//   change what you need and send it back.
	// - Changing `login_name` points the user account to another login and keeps the user ID. The new
	//   name must not belong to another user account (compared case-insensitively). Vaults that are
	//   21 CFR Part 11 compliant can be configured to refuse login name changes.
	// - `external_id` cannot be changed here ("Access denied."); leave it as read.
	// - The role `run_code_on_server` cannot be set through this service: the server removes it from
	//   the roles you send.
	// - Removing `can_log_in` logs the user's sessions out of the vault.
	rpc ModifyUser( ModifyUserRequest ) returns ( ModifyUserResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Removes a user account from the vault.
	//
	// - Removes the account and its private data: its views, notification rules, event subscriptions
	//   and group memberships are deleted. Requires the vault rights `manage_users` and
	//   `license_allows_modifications`; removing an account with the `full_control` role also requires
	//   `change_full_control_role`.
	// - The user stays in the Users value list (6) as a deleted item, so objects that refer to the
	//   user keep the reference. Bring the account back with
	//   [AddUser](mfiles:MFiles.IRPCUsersAdmin.AddUser) (`USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD`)
	//   or [UndeleteUserByGUID](mfiles:MFiles.IRPCUsersAdmin.UndeleteUserByGUID); the deleted views
	//   and rules do not come back.
	// - The login account is not removed.
	// - An account with an `external_id` can fail with "Access denied" ("... should be deleted via
	//   Manage").
	rpc RemoveUser( RemoveUserRequest ) returns ( RemoveUserResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a user account, or brings back a removed one with the same login name.
	//
	// - Same as [AddUser](mfiles:MFiles.IRPCUsersAdmin.AddUser) with `addition_mode`
	//   `USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD`, but without `tasks_before_login` in the
	//   response. Prefer [AddUser](mfiles:MFiles.IRPCUsersAdmin.AddUser).
	rpc AddOrUndeleteUser( AddOrUndeleteUserRequest ) returns ( AddOrUndeleteUserResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a user account during a directory import; brings back a removed account only when the
	// vault allows that.
	//
	// - **For M-Files components only.** M-Files Admin calls it when it imports users from a
	//   directory. Applications should not call it; use
	//   [AddUser](mfiles:MFiles.IRPCUsersAdmin.AddUser).
	// - Works like [AddOrUndeleteUser](mfiles:MFiles.IRPCUsersAdmin.AddOrUndeleteUser), except that a
	//   removed user is brought back only if the vault is configured to allow undeleting users in
	//   directory synchronization; otherwise a new account is always added.
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	rpc AddOrUndeleteUserViaADSync( AddOrUndeleteUserViaADSyncRequest ) returns ( AddOrUndeleteUserViaADSyncResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION internal: true };
	}

	// Gets one user account by ID.
	//
	// - Requires the vault right `manage_users`.
	// - A negative ID fails with "The parameter is incorrect."; an unknown ID (including 0) fails
	//   with "Not found.".
	rpc GetUser( GetUserRequest ) returns ( GetUserResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Finds the user account of a login name.
	//
	// - Requires the vault right `manage_users`.
	// - Matches the whole login name, case-insensitively; there are no wildcards or partial matches.
	//   Returns an empty list, not an error, when no account matches.
	rpc SearchForUser( SearchForUserRequest ) returns ( SearchForUserResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Brings back a removed user account, identified by its GUID in the Users value list.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	// - Never adds a new account. If no removed user has the GUID, the call fails with "Not found"
	//   (it does not return -1).
	// - Find the GUID of a removed user among the deleted items of the Users value list (6), for
	//   example with
	//   [SearchValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.SearchValueListItemsWithPermissions).
	rpc UndeleteUserByGUID( UndeleteUserByGUIDRequest ) returns ( UndeleteUserByGUIDResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a user account to the vault, or brings back a removed one.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`. A new account
	//   with the `full_control` role also requires `change_full_control_role`.
	// - `login_name` must not be empty ("The parameter is incorrect.") and must not belong to another
	//   user account (compared case-insensitively; "already exists").
	// - The role `run_code_on_server` cannot be granted here; the server removes it.
	// - `external_id` may be left empty; the server copies it from the login. A value that differs
	//   from the login's fails with "Access denied.".
	// - `addition_mode` decides what happens when a removed user with the same login name exists:
	//   `USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD` brings it back with its old user ID, so old
	//   references point to it again; `USER_ACCOUNT_ADDITION_MODE_ALWAYS_ADD` adds a new user ID.
	// - The response lists background tasks that prepare the new user's permissions. Until they
	//   complete, the user's login to the vault can be refused.
	rpc AddUser( AddUserRequest ) returns ( AddUserResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the user accounts that were added, changed or removed after a version token.
	//
	// - Requires the vault right `manage_users`.
	// - Available only for vaults on Microsoft SQL Server; other vaults fail with "Not implemented.".
	// - Start with `version_token` 0, then send the returned `version_token` in the next call. When
	//   nothing changed, the response has the same token and empty lists.
	// - Changes are returned oldest first. With `max_changes`, call again until the lists are empty.
	rpc GetChangedUserAccounts( GetChangedUserAccountsRequest ) returns ( GetChangedUserAccountsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether the vault meets the user identity precondition for projecting M-Files permissions
	// to Microsoft 365 storage.
	//
	// - **For M-Files components only.** M-Files Admin calls it before it saves the setting.
	//   Applications should not call it.
	// - Not available in this version: the server fails it with "Not implemented.".
	// - Requires the vault right `manage_users`. True when at least one user account with the
	//   `can_log_in` role has a Microsoft Entra object ID (a GUID) as `external_id`.
	rpc IsVaultReadyForM365StoragePermissions( IsVaultReadyForM365StoragePermissionsRequest ) returns ( IsVaultReadyForM365StoragePermissionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION internal: true };
	}
}

// The request of GetUsers.
message GetUsersRequest {
}

// The response of GetUsers.
message GetUsersResponse {

	// All user accounts. See [UserAccount](mfiles:MFiles.UserAccount).
	repeated UserAccount results = 1;
}

// The request of ModifyUser.
message ModifyUserRequest {

	// The complete new data of the account; `id` identifies the account to modify.
	UserAccount user_account = 1;
}

// The response of ModifyUser.
message ModifyUserResponse {
}

// The request of RemoveUser.
message RemoveUserRequest {

	// The ID of the user account to remove.
	int32 id = 1;
}

// The response of RemoveUser.
message RemoveUserResponse {
}

// The request of AddOrUndeleteUser.
message AddOrUndeleteUserRequest {

	// The new account. `login_name` is required; `id` is ignored. A removed user with the same login name is brought back with its old ID.
	UserAccount user_account = 1;
}

// The response of AddOrUndeleteUser.
message AddOrUndeleteUserResponse {

	// The ID of the new or restored user account.
	int32 id = 1;
}

// The request of AddOrUndeleteUserViaADSync.
message AddOrUndeleteUserViaADSyncRequest {

	// The new account. `login_name` is required; `id` is ignored.
	UserAccount user_account = 1;
}

// The response of AddOrUndeleteUserViaADSync.
message AddOrUndeleteUserViaADSyncResponse {

	// The ID of the new or restored user account.
	int32 id = 1;
}

// The request of GetUser.
message GetUserRequest {

	// The ID of the user account.
	int32 user = 1;
}

// The response of GetUser.
message GetUserResponse {

	// The user account. See [UserAccount](mfiles:MFiles.UserAccount).
	UserAccount putf8szua = 1;
}

// The request of SearchForUser.
message SearchForUserRequest {

	// The login name to look for, for example `MikeT` or `DOMAIN\user`.
	string account_name = 1;
}

// The response of SearchForUser.
message SearchForUserResponse {

	// The matching user account, or empty.
	repeated UserAccount results = 1;
}

// The request of UndeleteUserByGUID.
message UndeleteUserByGUIDRequest {

	// The GUID of the removed user's item in the Users value list (6).
	string account_to_undelete = 1;

	// The data to store in the restored account (`login_name`, vault roles, ...). `id` is ignored.
	UserAccount user_account_data = 2;
}

// The response of UndeleteUserByGUID.
message UndeleteUserByGUIDResponse {

	// The ID of the restored user account (the user's old ID).
	int32 account_id = 1;
}

// A structure that specifies an add user request.
message AddUserRequest {

	// The new account: `login_name`, `vault_roles`, and optionally `acl` and `user_language`. `id` is ignored.
	UserAccount user_account = 1;

	// Whether a removed account with the same login name is brought back. See [UserAccountAdditionMode](mfiles:MFiles.UserAccountAdditionMode).
	UserAccountAdditionMode addition_mode = 2;
}

// A structure that specifies an add user response.
message AddUserResponse {

	// The ID of the new or restored user account.
	int32 id = 1;

	// Background tasks that must complete before the user can log in to the vault.
	repeated AsyncTaskID tasks_before_login = 2;
}

// Request structure for the GetChangedUserAccounts method.
message GetChangedUserAccountsRequest {

	// The `version_token` of the previous response, or 0 for all changes.
	int64 version_token = 1;

	// The maximum number of changes to return; 0 for no limit.
	uint32 max_changes = 2;
}

// Response structure for the GetChangedUserAccounts method.
message GetChangedUserAccountsResponse {

	// Accounts added or changed after `version_token`.
	repeated UserAccount new_and_modified = 1;

	// IDs of accounts removed after `version_token`.
	repeated int32 deleted = 2;

	// The version of the last returned change; send it in the next call.
	int64 version_token = 3;
}

// The request of IsVaultReadyForM365StoragePermissions.
message IsVaultReadyForM365StoragePermissionsRequest {
}

// The response of IsVaultReadyForM365StoragePermissions.
message IsVaultReadyForM365StoragePermissionsResponse {

	// True if the vault meets the precondition.
	bool is_vault_ready = 1;
}