// 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/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_";

// Reads and sets the substitute users of users.
//
// 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](mfiles:MFiles.IRPCSubstituteUsers.GetSubstituteUsers) and
//   [SetSubstituteUsers](mfiles:MFiles.IRPCSubstituteUsers.SetSubstituteUsers). Any user can
//   manage their own list.
// - **Any user's substitutes, and the reverse lookup** (administration):
//   [GetSubstituteUsersOfUser](mfiles:MFiles.IRPCSubstituteUsers.GetSubstituteUsersOfUser) and
//   [GetUsersBySubstituteUser](mfiles:MFiles.IRPCSubstituteUsers.GetUsersBySubstituteUser). 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](mfiles:MFiles.IRPCSubstituteUsers.SetSubstituteUsers) fails with "Access
// denied.".
service IRPCSubstituteUsers {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Substitute users" };

	// Gets the substitutes of the calling user.
	//
	// - 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.
	rpc GetSubstituteUsers( GetSubstituteUsersRequest ) returns ( GetSubstituteUsersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Replaces the substitutes of the calling user.
	//
	// - 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.
	rpc SetSubstituteUsers( SetSubstituteUsersRequest ) returns ( SetSubstituteUsersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets the substitutes of any user (administration).
	//
	// - Requires the vault right `manage_users`; other users get "Access denied.".
	// - An unknown user ID returns an empty list.
	rpc GetSubstituteUsersOfUser( GetSubstituteUsersOfUserRequest ) returns ( GetSubstituteUsersOfUserResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets the users for whom a given user is a substitute, directly or through group membership
	// (administration).
	//
	// - 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.
	rpc GetUsersBySubstituteUser( GetUsersBySubstituteUserRequest ) returns ( GetUsersBySubstituteUserResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of GetSubstituteUsers.
message GetSubstituteUsersRequest {
}

// The response of GetSubstituteUsers.
message GetSubstituteUsersResponse {

	// The users (`USER_TYPE_USER`) and user groups (`USER_TYPE_USER_GROUP`) who substitute for the caller.
	repeated UserOrUserGroupID substitutes = 1;
}

// The request of SetSubstituteUsers.
message SetSubstituteUsersRequest {

	// The complete new list of substitutes: users (`USER_TYPE_USER`) and user groups (`USER_TYPE_USER_GROUP`).
	repeated UserOrUserGroupID substitutes = 1;
}

// The response of SetSubstituteUsers.
message SetSubstituteUsersResponse {
}

// The request of GetSubstituteUsersOfUser.
message GetSubstituteUsersOfUserRequest {

	// The ID of the user whose substitutes are wanted.
	int32 user_id = 1;
}

// The response of GetSubstituteUsersOfUser.
message GetSubstituteUsersOfUserResponse {

	// The users and user groups who substitute for that user.
	repeated UserOrUserGroupID substitutes = 1;
}

// The request of GetUsersBySubstituteUser.
message GetUsersBySubstituteUserRequest {

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

// The response of GetUsersBySubstituteUser.
message GetUsersBySubstituteUserResponse {

	// The users (`USER_TYPE_USER`) for whom `user_id` is a substitute.
	repeated UserOrUserGroupID users = 1;
}