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

// Administers class groups: reads, adds, modifies and removes the groups that organize document
// classes.
//
// Use this interface to add, modify and delete document class groups in a vault.
//
// A class group bundles document classes. Class groups are items of the built-in value list 2.
// M-Files Admin calls this service; applications read class groups with
// [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups), which
// needs no special rights and also returns the classes with the caller's permissions.
//
// - **Session and rights.** Every method requires a vault session.
//   [GetDocClassGroups](mfiles:MFiles.IRPCDocClassGroupsAdmin.GetDocClassGroups) needs the vault
//   right `read_all_metadata_structure` (a normal user gets "Access denied."). The write
//   methods need `change_metadata_structure` and `license_allows_modifications`.
// - **Calls**: [GetDocClassGroups](mfiles:MFiles.IRPCDocClassGroupsAdmin.GetDocClassGroups),
//   [AddDocClassGroup](mfiles:MFiles.IRPCDocClassGroupsAdmin.AddDocClassGroup),
//   [ModifyDocClassGroup](mfiles:MFiles.IRPCDocClassGroupsAdmin.ModifyDocClassGroup),
//   [RemoveDocClassGroup](mfiles:MFiles.IRPCDocClassGroupsAdmin.RemoveDocClassGroup). The classes
//   themselves are in [IRPCPropertyDefsAdmin](mfiles:MFiles.IRPCPropertyDefsAdmin); value list 2
//   cannot be edited with the item methods of
//   [IRPCObjectTypesAdmin](mfiles:MFiles.IRPCObjectTypesAdmin).
// - **Metadata structure version.** Every successful add, modify and remove increments the vault's metadata
//   version when it commits. The methods do not send the `mfiles-metadata-version-bin` trailer;
//   see [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/).
service IRPCDocClassGroupsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Class groups" };

	// Deletes a class group.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
	//   group.
	// - The member classes are not deleted. Existing documents of those classes are updated so that
	//   they no longer refer to the group.
	// - Increments the metadata structure version.
	rpc RemoveDocClassGroup( RemoveDocClassGroupRequest ) returns ( RemoveDocClassGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Creates a class group.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`.
	// - Only document classes can be grouped: `object_type` must be 0 (Document), otherwise the call
	//   fails with an invalid-argument error.
	// - Increments the metadata structure version.
	rpc AddDocClassGroup( AddDocClassGroupRequest ) returns ( AddDocClassGroupResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all class groups with their member classes.
	//
	// - Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
	//   Without that right, use
	//   [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups).
	// - Returned 7 groups in the Sample Vault. The order is undefined.
	rpc GetDocClassGroups( GetDocClassGroupsRequest ) returns ( GetDocClassGroupsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Saves a changed class group: its name and member classes.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
	//   group. `object_type` must be 0 (Document), as in
	//   [AddDocClassGroup](mfiles:MFiles.IRPCDocClassGroupsAdmin.AddDocClassGroup).
	// - Classes added to or removed from `member_classes` change the class-group information of
	//   existing documents of those classes.
	// - Increments the metadata structure version.
	rpc ModifyDocClassGroup( ModifyDocClassGroupRequest ) returns ( ModifyDocClassGroupResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of RemoveDocClassGroup.
message RemoveDocClassGroupRequest {

	// The ID of the class group to delete.
	int32 id = 1;
}

// The response of RemoveDocClassGroup.
message RemoveDocClassGroupResponse {
}

// The request of AddDocClassGroup.
message AddDocClassGroupRequest {

	// The new [ClassGroup](mfiles:MFiles.ClassGroup) with its name and member classes. `id` is ignored and assigned by the server.
	ClassGroup class_group = 1;
}

// The response of AddDocClassGroup.
message AddDocClassGroupResponse {

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

// The request of GetDocClassGroups.
message GetDocClassGroupsRequest {
}

// The response of GetDocClassGroups.
message GetDocClassGroupsResponse {

	// One [ClassGroup](mfiles:MFiles.ClassGroup) per class group.
	repeated ClassGroup class_groups = 1;
}

// The request of ModifyDocClassGroup.
message ModifyDocClassGroupRequest {

	// The complete new [ClassGroup](mfiles:MFiles.ClassGroup); `id` identifies the group to modify.
	ClassGroup class_group = 1;
}

// The response of ModifyDocClassGroup.
message ModifyDocClassGroupResponse {
}