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

// Adds, reads, modifies and removes the user groups of a vault and their members.
//
// Use this interface to add, modify and delete user groups in a vault.
//
// A user group consists of members. A member can be a user account
// or another user group. A special type of user group is a Windows Group
// that refers to an existing Windows local or global group. The
// members of a Windows Group are not defined in the vault database
// but are instead queried from Windows whenever needed.
//
// M-Files Admin uses this service for the User groups node of a vault and for importing Windows
// groups. All methods need a vault session whose user has the vault right `manage_users`
// ([VaultAccess](mfiles:MFiles.VaultAccess)); the write methods also need
// `license_allows_modifications`.
//
// - **Members.** `UserGroup.user_group.members` lists user account IDs as positive numbers and
//   member groups as negative numbers (group 102 is -102). The same convention applies to
//   `member_id` of [AddMemberToUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddMemberToUserGroup)
//   and [RemoveMemberFromUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.RemoveMemberFromUserGroup).
// - **Built-in groups.** 1 "All internal users" and 2 "All internal and external users" are
//   returned with empty `members`: their membership follows from the users' `is_internal_user`
//   role. They can be renamed but not given members or removed.
// - **External Windows groups** (`is_external_windows_group`) mirror a group of the domain
//   directory. [SyncExternalWindowsGroup](mfiles:MFiles.IRPCUserGroupsAdmin.SyncExternalWindowsGroup)
//   updates their members;
//   [GetUserGroupSyncStatus](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupSyncStatus) reports
//   the last synchronization.
// - **Group types.** Besides normal groups (`USER_GROUP_TYPE_NORMAL`), a vault can have groups that
//   represent users and groups of an external repository.
//   [GetUserGroupsAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupsAdmin) returns normal groups
//   only; [GetUserContainersAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserContainersAdmin) returns
//   all types.
//
// Methods by task:
//
// - **Read:** [GetUserGroupsAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupsAdmin),
//   [GetUserGroupAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupAdmin),
//   [GetUserContainersAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserContainersAdmin),
//   [GetChangedUserGroups](mfiles:MFiles.IRPCUserGroupsAdmin.GetChangedUserGroups).
// - **Add, change, remove:** [AddUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddUserGroup),
//   [AddOrUndeleteUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddOrUndeleteUserGroup),
//   [ModifyUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.ModifyUserGroup),
//   [RemoveUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.RemoveUserGroup).
// - **Change one membership** without sending the whole group:
//   [AddMemberToUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddMemberToUserGroup),
//   [RemoveMemberFromUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.RemoveMemberFromUserGroup).
//
// Users without `manage_users` read groups with
// [GetUserGroups](mfiles:MFiles.IRPCVault.GetUserGroups) of
// [IRPCVault](mfiles:MFiles.IRPCVault). Users are managed with
// [IRPCUsersAdmin](mfiles:MFiles.IRPCUsersAdmin).
service IRPCUserGroupsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "User groups" };

	// Removes a user group from the vault.
	//
	// - Removes the group and its memberships. Requires the vault rights `manage_users` and
	//   `license_allows_modifications`.
	// - The built-in groups 1 and 2 cannot be removed.
	rpc RemoveUserGroup( RemoveUserGroupRequest ) returns ( RemoveUserGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Updates the members of an external Windows group from the domain directory.
	//
	// - Reads the group's members from the directory and updates the group, adding user accounts for
	//   new members as needed. Large groups can take a long time.
	// - Requires the vault right `manage_users`. A group that is not an external Windows group fails;
	//   an unknown ID fails with "Not found.".
	// - The result is recorded for
	//   [GetUserGroupSyncStatus](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupSyncStatus).
	rpc SyncExternalWindowsGroup( SyncExternalWindowsGroupRequest ) returns ( SyncExternalWindowsGroupResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a user group to the vault.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	// - The name must be unique among the vault's groups; a duplicate fails with "already exists".
	//   To bring back a removed group with the same name, use
	//   [AddOrUndeleteUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddOrUndeleteUserGroup).
	// - Members use the sign convention of the service overview (groups negative).
	rpc AddUserGroup( AddUserGroupRequest ) returns ( AddUserGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all normal user groups of the vault, with their members.
	//
	// - Requires the vault right `manage_users`. Returns groups of type `USER_GROUP_TYPE_NORMAL`
	//   only; use [GetUserContainersAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserContainersAdmin)
	//   for all types. The order is not specified.
	// - The built-in groups 1 and 2 have empty `members`.
	rpc GetUserGroupsAdmin( GetUserGroupsAdminRequest ) returns ( GetUserGroupsAdminResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Replaces the data and members of an existing user group.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	// - Send the complete group: read it with
	//   [GetUserGroupAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupAdmin), change what you need
	//   and send it back. `members` replaces the old member list. To add or remove one member, use
	//   [AddMemberToUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddMemberToUserGroup) or
	//   [RemoveMemberFromUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.RemoveMemberFromUserGroup).
	// - The built-in groups 1 and 2 can be renamed, but their `members` must be empty.
	rpc ModifyUserGroup( ModifyUserGroupRequest ) returns ( ModifyUserGroupResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a user group, or brings back a removed group with the same name.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	// - If a removed group has the same name, it is restored with its old ID, so permissions that
	//   refer to it apply again. An existing group with the same name fails with "already exists".
	// - Fails with "The parameter is incorrect." on servers configured not to refresh the user groups
	//   list when groups are added through the API.
	rpc AddOrUndeleteUserGroup( AddOrUndeleteUserGroupRequest ) returns ( AddOrUndeleteUserGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets one user group of any type, with its members.
	//
	// - Requires the vault right `manage_users`. An unknown ID fails with "Not found.".
	rpc GetUserGroupAdmin( GetUserGroupAdminRequest ) returns ( GetUserGroupAdminResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all user groups of the vault, including the groups that represent external repository
	// users and groups.
	//
	// - Requires the vault right `manage_users`. Like
	//   [GetUserGroupsAdmin](mfiles:MFiles.IRPCUserGroupsAdmin.GetUserGroupsAdmin), but returns groups
	//   of every [UserGroupType](mfiles:MFiles.UserGroupType).
	rpc GetUserContainersAdmin( GetUserContainersAdminRequest ) returns ( GetUserContainersAdminResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds one user or group to a user group, if it is not a member yet.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	// - Does nothing if the member is already in the group, so the call can be repeated safely.
	// - The member must suit the group's type; an unknown group fails with "Not found.".
	rpc AddMemberToUserGroup( AddMemberToUserGroupRequest ) returns ( AddMemberToUserGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Removes one user or group from a user group, if it is a member.
	//
	// - Requires the vault rights `manage_users` and `license_allows_modifications`.
	// - Removes only a direct membership.
	rpc RemoveMemberFromUserGroup( RemoveMemberFromUserGroupRequest ) returns ( RemoveMemberFromUserGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the user groups 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.".
	// - Works like [GetChangedUserAccounts](mfiles:MFiles.IRPCUsersAdmin.GetChangedUserAccounts): start
	//   with `version_token` 0 and send the returned token in the next call. Changes are returned
	//   oldest first.
	rpc GetChangedUserGroups( GetChangedUserGroupsRequest ) returns ( GetChangedUserGroupsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the result of the last synchronization of an external Windows group.
	//
	// - Requires the vault right `manage_users`.
	// - The response has no `status` when nothing has been recorded for the group, including groups
	//   that are not external Windows groups and unknown IDs; it does not fail.
	rpc GetUserGroupSyncStatus( GetUserGroupSyncStatusRequest ) returns ( GetUserGroupSyncStatusResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of RemoveUserGroup.
message RemoveUserGroupRequest {

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

// The response of RemoveUserGroup.
message RemoveUserGroupResponse {
}

// The request of SyncExternalWindowsGroup.
message SyncExternalWindowsGroupRequest {

	// The ID of the external Windows group to synchronize.
	int32 id = 1;
}

// The response of SyncExternalWindowsGroup.
message SyncExternalWindowsGroupResponse {
}

// The request of AddUserGroup.
message AddUserGroupRequest {

	// The new group. `user_group.id` is ignored; the server assigns the ID.
	UserGroup usergroup = 1;

	// True to record the member user accounts as imported through this group. M-Files Admin sets it when it imports a Windows group with its users; leave it false otherwise.
	bool add_memebers_as_imported_users = 2;
}

// The response of AddUserGroup.
message AddUserGroupResponse {

	// The ID of the new user group.
	int32 id = 1;
}

// The request of GetUserGroupsAdmin.
message GetUserGroupsAdminRequest {
}

// The response of GetUserGroupsAdmin.
message GetUserGroupsAdminResponse {

	// The user groups. See [UserGroup](mfiles:MFiles.UserGroup).
	repeated UserGroup values = 1;
}

// The request of ModifyUserGroup.
message ModifyUserGroupRequest {

	// The complete new data of the group; `user_group.id` identifies the group.
	UserGroup usergroup = 1;
}

// The response of ModifyUserGroup.
message ModifyUserGroupResponse {
}

// The request of AddOrUndeleteUserGroup.
message AddOrUndeleteUserGroupRequest {

	// The group. `user_group.id` is ignored.
	UserGroup usergroup = 1;

	// See [AddUserGroup](mfiles:MFiles.IRPCUserGroupsAdmin.AddUserGroup); leave false.
	bool add_memebers_as_imported_users = 2;
}

// The response of AddOrUndeleteUserGroup.
message AddOrUndeleteUserGroupResponse {

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

// The request of GetUserGroupAdmin.
message GetUserGroupAdminRequest {

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

// The response of GetUserGroupAdmin.
message GetUserGroupAdminResponse {

	// The user group. See [UserGroup](mfiles:MFiles.UserGroup).
	UserGroup usergroup = 1;
}

// The request of GetUserContainersAdmin.
message GetUserContainersAdminRequest {
}

// The response of GetUserContainersAdmin.
message GetUserContainersAdminResponse {

	// The user groups of all types.
	repeated UserGroup values = 1;
}

// The request of AddMemberToUserGroup.
message AddMemberToUserGroupRequest {

	// The ID of the group to add the member to.
	int32 user_group = 1;

	// The user account ID, or the negated ID of a user group (-102 for group 102).
	int32 member_id = 2;
}

// The response of AddMemberToUserGroup.
message AddMemberToUserGroupResponse {
}

// The request of RemoveMemberFromUserGroup.
message RemoveMemberFromUserGroupRequest {

	// The ID of the group to remove the member from.
	int32 user_group = 1;

	// The user account ID, or the negated ID of a user group (-102 for group 102).
	int32 member_id = 2;
}

// The response of RemoveMemberFromUserGroup.
message RemoveMemberFromUserGroupResponse {
}

// Request structure for the GetChangedUserGroups method.
message GetChangedUserGroupsRequest {

	// 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 GetChangedUserGroups method.
message GetChangedUserGroupsResponse {

	// Groups added or changed after `version_token`.
	repeated UserGroup new_and_modified = 1;

	// IDs of groups 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;
}

// Request structure for the GetUserGroupSyncStatus method.
message GetUserGroupSyncStatusRequest {

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

// Response structure for the GetUserGroupSyncStatus method.
message GetUserGroupSyncStatusResponse {

	// The last synchronization: time, synchronized and skipped user counts, and errors. Unset if none is recorded.
	UserGroupSyncStatus status = 1;
}