// 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 property definitions and classes: reads their full definitions, adds, modifies and
// removes them, and starts recalculation of automatic values.
//
// Use this interface to add, modify and remove property definitions.
//
// This is the administrator's side of [IRPCPropertyDefs](mfiles:MFiles.IRPCPropertyDefs).
// M-Files Admin and administrative tools call it; ordinary applications read property definitions
// and classes with the Vault API instead.
//
// | | Vault API (read side) | This service |
// | --- | --- | --- |
// | Property definitions | [GetPropertyDefs](mfiles:MFiles.IRPCPropertyDefs.GetPropertyDefs): [PropertyDef](mfiles:MFiles.PropertyDef) | [GetPropertyDefsAdmin](mfiles:MFiles.IRPCPropertyDefsAdmin.GetPropertyDefsAdmin): [PropertyDefAdmin](mfiles:MFiles.PropertyDefAdmin), adding automatic value and validation settings and aliases |
// | Classes | [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups) | [GetObjectClasses](mfiles:MFiles.IRPCPropertyDefsAdmin.GetObjectClasses): [DocClass](mfiles:MFiles.DocClass), with workflow, name property and aliases |
// | Rights | none | see below |
//
// - **Session and rights.** Every method requires a vault session. Writes need the vault rights
//   `change_metadata_structure` and `license_allows_modifications`. Most reads need
//   `read_all_metadata_structure`;
//   [GetObjectClasses](mfiles:MFiles.IRPCPropertyDefsAdmin.GetObjectClasses) and
//   [GetAssociatedPropertyDefs](mfiles:MFiles.IRPCPropertyDefsAdmin.GetAssociatedPropertyDefs)
//   need no vault rights. Setting or changing VBScript code needs a
//   code-execution right (see [AddPropertyDef](mfiles:MFiles.IRPCPropertyDefsAdmin.AddPropertyDef)).
// - **Property definitions**:
//   [GetPropertyDefsAdmin](mfiles:MFiles.IRPCPropertyDefsAdmin.GetPropertyDefsAdmin),
//   [GetPropertyDefAdmin](mfiles:MFiles.IRPCPropertyDefsAdmin.GetPropertyDefAdmin),
//   [AddPropertyDef](mfiles:MFiles.IRPCPropertyDefsAdmin.AddPropertyDef),
//   [UpdatePropertyDef](mfiles:MFiles.IRPCPropertyDefsAdmin.UpdatePropertyDef),
//   [RemovePropertyDef](mfiles:MFiles.IRPCPropertyDefsAdmin.RemovePropertyDef),
//   [GetLastUsedValue](mfiles:MFiles.IRPCPropertyDefsAdmin.GetLastUsedValue),
//   [IsPropertyFullTextSearchIndexable](mfiles:MFiles.IRPCPropertyDefsAdmin.IsPropertyFullTextSearchIndexable).
// - **Classes**:
//   [GetObjectClasses](mfiles:MFiles.IRPCPropertyDefsAdmin.GetObjectClasses),
//   [GetAssociatedPropertyDefs](mfiles:MFiles.IRPCPropertyDefsAdmin.GetAssociatedPropertyDefs),
//   [AddObjectClass](mfiles:MFiles.IRPCPropertyDefsAdmin.AddObjectClass),
//   [ModifyObjectClass](mfiles:MFiles.IRPCPropertyDefsAdmin.ModifyObjectClass),
//   [RemoveObjectClass](mfiles:MFiles.IRPCPropertyDefsAdmin.RemoveObjectClass). Class groups
//   are in [IRPCDocClassGroupsAdmin](mfiles:MFiles.IRPCDocClassGroupsAdmin).
// - **Update existing objects** (server-level jobs):
//   [RecalculateProperty](mfiles:MFiles.IRPCPropertyDefsAdmin.RecalculateProperty),
//   [UpdateObjectNames](mfiles:MFiles.IRPCPropertyDefsAdmin.UpdateObjectNames).
//
// **Metadata structure version.** Adding, updating and removing a property definition increments both
// `property_defs_version` and the vault's metadata structure version (see
// [GetMetadataStructureVersion](mfiles:MFiles.IRPCVault.GetMetadataStructureVersion)); class
// changes increment the metadata structure version.
// The methods of this service 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 IRPCPropertyDefsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Property definition and class administration" };

	// Gets the properties of a class: the property definitions associated with it and whether each is
	// required.
	//
	// - Requires a vault session; no vault rights are needed.
	// - Class 0 returned 12 associations in the Sample Vault.
	rpc GetAssociatedPropertyDefs( GetAssociatedPropertyDefsRequest ) returns ( GetAssociatedPropertyDefsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes a property definition and its values from all objects, or only counts the values that
	// would be removed.
	//
	// - With `check_effects_only` false: **deletes all values of the property from the vault**, and the
	//   views and similar elements that use it. Use `copy_to_another_property_def` to move the values
	//   to another property definition first. This cannot be undone.
	// - With `check_effects_only` true: changes nothing and returns the counts in `null_values` and
	//   `non_null_values`. Otherwise both counts are 0.
	// - Requires `change_metadata_structure` and `license_allows_modifications`.
	// - Built-in property definitions cannot be removed. A property definition used by classes fails
	//   with an error that names the classes, unless `delete_from_classes_if_necessary` is true.
	// - Increments `property_defs_version` and the metadata structure version.
	rpc RemovePropertyDef( RemovePropertyDefRequest ) returns ( RemovePropertyDefResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes a class.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
	//   class.
	// - Built-in classes cannot be removed.
	// - Objects of the class may exist: the class is then only marked deleted, new objects cannot use
	//   it, and existing objects keep their property values.
	// - Removes the class from its class groups. Increments the metadata structure version.
	rpc RemoveObjectClass( RemoveObjectClassRequest ) returns ( RemoveObjectClassResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Starts a server job that recalculates the names of all objects of a class from the class's name
	// property.
	//
	// - Starts a temporary server-level scheduled job and returns before it completes. `task_id` is the
	//   job's ID; M-Files Admin follows it with
	//   [GetScheduledJobRunInfo](mfiles:MFiles.IRPCScheduledJobsAdmin.GetScheduledJobRunInfo) from a
	//   server-level session.
	// - Requires `change_metadata_structure` and `license_allows_modifications`.
	// - Fails with an invalid-argument error when the class uses Name or title (property 0) as its name
	//   property: there is nothing to recalculate.
	rpc UpdateObjectNames( UpdateObjectNamesRequest ) returns ( UpdateObjectNamesResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Starts a server job that recalculates the automatic values of a property in all existing objects.
	//
	// - Starts a temporary server-level scheduled job and returns before it completes. `task_id` is the
	//   job's ID; M-Files Admin follows it with
	//   [GetScheduledJobRunInfo](mfiles:MFiles.IRPCScheduledJobsAdmin.GetScheduledJobRunInfo) from a
	//   server-level session.
	// - Changes property values of existing objects. Requires `change_metadata_structure` and
	//   `license_allows_modifications`.
	rpc RecalculateProperty( RecalculatePropertyRequest ) returns ( RecalculatePropertyResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the administrative definitions of all classes.
	//
	// - Requires a vault session; no vault rights are needed. A normal user got all 41 classes of the
	//   Sample Vault, the same as an administrator.
	// - Names are in the session language. For class groups and the per-user permissions of classes,
	//   use [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups).
	rpc GetObjectClasses( GetObjectClassesRequest ) returns ( GetObjectClassesResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Creates a class with its property associations.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`.
	// - If the class's `name_property_def` is not Name or title (0), the server resets that property
	//   definition's permissions so that all users can see and edit it.
	// - Increments the metadata structure version.
	rpc AddObjectClass( AddObjectClassRequest ) returns ( AddObjectClassResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the administrative definitions of all property definitions.
	//
	// - Requires `read_all_metadata_structure`; a normal user gets "Access denied.". Users
	//   without the right call [GetPropertyDefs](mfiles:MFiles.IRPCPropertyDefs.GetPropertyDefs).
	// - Returned 150 property definitions in the Sample Vault, built-in ones included.
	rpc GetPropertyDefsAdmin( GetPropertyDefsAdminRequest ) returns ( GetPropertyDefsAdminResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the administrative definition of one property definition.
	//
	// - Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
	// - An unknown ID fails with `Unknown property definition "<id>".`.
	rpc GetPropertyDefAdmin( GetPropertyDefAdminRequest ) returns ( GetPropertyDefAdminResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Creates a property definition.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`.
	// - VBScript code (automatic numbering or calculation with code, or validation with code) also
	//   requires the server right `run_code`; code with a valid signature needs only the vault right
	//   `run_signed_code`.
	// - `property_def.is_predefined` true, or an `update_type` other than `UPDATE_TYPE_NORMAL`, fails
	//   with an invalid-argument error.
	// - Increments `property_defs_version` and the metadata structure version.
	rpc AddPropertyDef( AddPropertyDefRequest ) returns ( AddPropertyDefResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the last number used by an automatic numbering property.
	//
	// - Requires `read_all_metadata_structure`.
	// - For a property definition without automatic numbering the value is empty (for example property 0).
	rpc GetLastUsedValue( GetLastUsedValueRequest ) returns ( GetLastUsedValueResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether the values of a property definition are indexed for full-text search.
	//
	// - Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
	// - Name or title (0) returned true.
	rpc IsPropertyFullTextSearchIndexable( IsPropertyFullTextSearchIndexableRequest ) returns ( IsPropertyFullTextSearchIndexableResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Saves a changed property definition.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`, plus the code rights
	//   described in [AddPropertyDef](mfiles:MFiles.IRPCPropertyDefsAdmin.AddPropertyDef) when VBScript
	//   code is set or changed.
	// - `data_type`, `is_based_on_value_list`, `value_list` and `update_type` cannot change: send them
	//   exactly as stored.
	// - Applying changed automatic permissions to existing objects runs as background tasks, returned
	//   in `async_task_ids`; follow them with
	//   [GetAsyncTask](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetAsyncTask).
	// - Increments `property_defs_version` and the metadata structure version.
	rpc UpdatePropertyDef( UpdatePropertyDefRequest ) returns ( UpdatePropertyDefResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Saves a changed class and, optionally, its property associations.
	//
	// - Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
	//   class.
	// - Adding or removing properties of existing objects runs as background tasks, returned in
	//   `async_task_ids`; follow them with
	//   [GetAsyncTask](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetAsyncTask).
	// - The same name-property permission rule as in
	//   [AddObjectClass](mfiles:MFiles.IRPCPropertyDefsAdmin.AddObjectClass) applies.
	// - Increments the metadata structure version.
	rpc ModifyObjectClass( ModifyObjectClassRequest ) returns ( ModifyObjectClassResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of GetAssociatedPropertyDefs.
message GetAssociatedPropertyDefsRequest {

	// The ID of the class.
	int32 document_profile = 1;
}

// The response of GetAssociatedPropertyDefs.
message GetAssociatedPropertyDefsResponse {

	// One [AssociatedPropertyDef](mfiles:MFiles.AssociatedPropertyDef) per property of the class.
	repeated AssociatedPropertyDef values = 1;
}

// The request of RemovePropertyDef.
message RemovePropertyDefRequest {

	// The ID of the PropertyDef to remove.
	int32 property_def = 1;

	// True to move the values to `target_property_def` before deleting.
	bool copy_to_another_property_def = 2;

	// The property definition that receives the values. Used only when `copy_to_another_property_def` is true.
	int32 target_property_def = 3;

	// True to add the moved values to the target's existing values, false to overwrite them.
	bool append = 4;

	// True to remove the property definition from the classes that use it; false to fail if any class uses it.
	bool delete_from_classes_if_necessary = 5;

	// True if the server should only check the effects of these changes to existing documents and not apply the changes yet.
	bool check_effects_only = 6;
}

// The response of RemovePropertyDef.
message RemovePropertyDefResponse {

	// With `check_effects_only`, the number of empty values that would be removed.
	uint32 null_values = 1;

	// With `check_effects_only`, the number of non-empty values that would be removed.
	uint32 non_null_values = 2;
}

// The request of RemoveObjectClass.
message RemoveObjectClassRequest {

	// The ID of the object class to remove.
	int32 class_id = 1;
}

// The response of RemoveObjectClass.
message RemoveObjectClassResponse {
}

// The request of UpdateObjectNames.
message UpdateObjectNamesRequest {

	// The ID of the class whose objects are renamed.
	int32 doc_class = 1;
}

// The response of UpdateObjectNames.
message UpdateObjectNamesResponse {

	// The ID of the scheduled job that does the work.
	int32 task_id = 1;
}

// The request of RecalculateProperty.
message RecalculatePropertyRequest {

	// The ID of the property to recalculate.
	int32 property_def = 1;

	// True to fill in only empty values, false to recalculate every value.
	bool null_values_only = 2;
}

// The response of RecalculateProperty.
message RecalculatePropertyResponse {

	// The ID of the scheduled job that does the work.
	int32 task_id = 1;
}

// The request of GetObjectClasses.
message GetObjectClassesRequest {
}

// The response of GetObjectClasses.
message GetObjectClassesResponse {

	// One [DocClass](mfiles:MFiles.DocClass) per class. The class ID is `value_list_item.item_info.obj_id.item_id.internal_id`.
	repeated DocClass values = 1;
}

// The request of AddObjectClass.
message AddObjectClassRequest {

	// The new class. The item ID and GUID in `value_list_item` are ignored and assigned by the server; `object_type` sets the object type of the class.
	DocClass doc_class = 1;

	// The properties of the class and whether each is required.
	repeated AssociatedPropertyDef property_defs = 2;
}

// The response of AddObjectClass.
message AddObjectClassResponse {

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

// The request of GetPropertyDefsAdmin.
message GetPropertyDefsAdminRequest {
}

// The response of GetPropertyDefsAdmin.
message GetPropertyDefsAdminResponse {

	// One [PropertyDefAdmin](mfiles:MFiles.PropertyDefAdmin) per property definition.
	repeated PropertyDefAdmin values = 1;
}

// The request of GetPropertyDefAdmin.
message GetPropertyDefAdminRequest {

	// The ID of the property definition.
	int32 property_def = 1;
}

// The response of GetPropertyDefAdmin.
message GetPropertyDefAdminResponse {

	// The definition. See [PropertyDefAdmin](mfiles:MFiles.PropertyDefAdmin).
	PropertyDefAdmin ppropdefadmin = 1;
}

// The request of AddPropertyDef.
message AddPropertyDefRequest {

	// The new property definition. The ID (`property_def.id`) and GUID are ignored and assigned by the server.
	PropertyDefAdmin propdefadmin = 1;

	// For an automatic numbering property, the number to continue from. Leave unset otherwise.
	TypedValue reset_last_used_value = 2;
}

// The response of AddPropertyDef.
message AddPropertyDefResponse {

	// The property definition as stored, with its new ID.
	PropertyDefAdmin new_property_definition = 1;
}

// The request of GetLastUsedValue.
message GetLastUsedValueRequest {

	// The PropertyDef to get.
	int32 property_def = 1;
}

// The response of GetLastUsedValue.
message GetLastUsedValueResponse {

	// Receives the result.
	TypedValue last_used_value = 1;
}

// The request of IsPropertyFullTextSearchIndexable.
message IsPropertyFullTextSearchIndexableRequest {

	// The PropertyDef to get information on.
	int32 property_def = 1;
}

// The response of IsPropertyFullTextSearchIndexable.
message IsPropertyFullTextSearchIndexableResponse {

	// Receives true if indexable, false otherwise.
	bool indexable = 1;
}

// The request of UpdatePropertyDef.
message UpdatePropertyDefRequest {

	// The complete new definition; `property_def.id` identifies it. Start from [GetPropertyDefAdmin](mfiles:MFiles.IRPCPropertyDefsAdmin.GetPropertyDefAdmin).
	PropertyDefAdmin propdefadmin = 1;

	// For an automatic numbering property, the number to continue from. Leave unset to keep the current one.
	TypedValue reset_last_used_value = 2;

	// Used only when the change turns on automatic permissions: true to make them active on existing objects, false to add them inactive.
	bool automatic_permissions_forced_active = 3;
}

// The response of UpdatePropertyDef.
message UpdatePropertyDefResponse {

	// Asynchronous task identifiers, if any, related to the change.
	repeated AsyncTaskID async_task_ids = 1;
}

// The request of ModifyObjectClass.
message ModifyObjectClassRequest {

	// The complete new class; `value_list_item.item_info.obj_id.item_id.internal_id` identifies it.
	DocClass doc_class = 1;

	// True to make changed automatic permissions active on the objects of the class, false to add them inactive.
	bool automatic_permissions_forced_active = 2;

	// True to replace the class's property associations with `property_defs`.
	bool modify_associations = 3;

	// The new property associations. Ignored when `modify_associations` is false.
	repeated AssociatedPropertyDef property_defs = 4;
}

// The response of ModifyObjectClass.
message ModifyObjectClassResponse {

	// The ID of the last background task that adds or removes properties of existing objects, or -1 if there is none. It is also in `async_task_ids`.
	int64 task_idchange_objects = 1;

	// All background tasks started by the change.
	repeated AsyncTaskID async_task_ids = 2;
}