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

// Monitors the vault's background work: refreshes of external object types and external
// locations, and the queue of asynchronous tasks.
//
// Use this interface to start, stop and query background operations.
//
// M-Files Admin uses this service to show and start background refreshes and to list the vault's
// asynchronous tasks. Every method needs a vault session and the vault right
// `change_metadata_structure` (part of full control); a normal user gets "Access denied.". The exception is
// [CheckAndRegisterMultiServerResponsibility](mfiles:MFiles.IRPCBackgroundOperationsAdmin.CheckAndRegisterMultiServerResponsibility),
// which is for an M-Files component.
//
// **Background operations** are identified by a
// [BackgroundOperationID](mfiles:MFiles.BackgroundOperationID): `type` and `id`. M-Files Admin uses
// `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_OBJECT_TYPE` with the object type ID and
// `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_LOCATION` with the external location ID. Start one with
// [StartBackgroundOperation](mfiles:MFiles.IRPCBackgroundOperationsAdmin.StartBackgroundOperation),
// then follow it with
// [GetBackgroundOperationStatus](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetBackgroundOperationStatus)
// or block with
// [WaitForBackgroundOperationCompletion](mfiles:MFiles.IRPCBackgroundOperationsAdmin.WaitForBackgroundOperationCompletion).
//
// **Asynchronous tasks** ([AsyncTask](mfiles:MFiles.AsyncTask)) are work items that the vault queues
// and runs later, for example permission updates after a change (`ACLPseudoUserPropagation`,
// `RefreshObjectsACL`) or preview file generation (`GenerateViewerFiles`). Task IDs grow over
// time. Read them with
// [GetAsyncTasksRange](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetAsyncTasksRange) or
// [GetAsyncTask](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetAsyncTask), and wait for them with
// [WaitForAsyncTaskCompletion](mfiles:MFiles.IRPCBackgroundOperationsAdmin.WaitForAsyncTaskCompletion).
//
// To wait until the vault has finished all background work queued so far (for example in a test,
// after a change that triggers permission updates):
//
// 1. [QueueAndGetLatestAsyncTask](mfiles:MFiles.IRPCBackgroundOperationsAdmin.QueueAndGetLatestAsyncTask);
//    stop if `is_available` is false.
// 2. [WaitForAsyncTaskCompletion](mfiles:MFiles.IRPCBackgroundOperationsAdmin.WaitForAsyncTaskCompletion)
//    with `async_tasks` = [that task's ID] and `tasks_request` = { `async_task_start`: the same ID,
//    `max_count`: 50, `latest`: true, `filters`: 3 (queued or running) }.
// 3. Repeat step 2 with the IDs in `tasks_response.async_tasks` until it is empty.
service IRPCBackgroundOperationsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Background operations" };

	// Tells whether this server is the one in a multi-server vault that runs the reporting data
	// exports, and claims that role if no server has it.
	//
	// **For M-Files components only.** M-Files Reporting Data Services calls it so that only one
	// server of a multi-server vault runs the data exports. Applications should not call it.
	//
	// - Requires a vault session and the server right `manage_jobs` (system administrator server
	//   role).
	// - On a single server it always returns true. In multi-server mode only the operation ID
	//   `mfdataexport` is accepted; other IDs fail with "The parameter is incorrect.".
	rpc CheckAndRegisterMultiServerResponsibility( CheckAndRegisterMultiServerResponsibilityRequest ) returns ( CheckAndRegisterMultiServerResponsibilityResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION internal: true };
	}

	// Gets the vault's asynchronous tasks, newest first.
	//
	// - Requires a vault session and the vault right `change_metadata_structure`.
	// - Can return a very large list (up to 2,000,000 tasks). Prefer
	//   [GetAsyncTasksRange](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetAsyncTasksRange), which
	//   pages and filters.
	rpc GetAsyncTasks( GetAsyncTasksRequest ) returns ( GetAsyncTasksResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets one asynchronous task by ID.
	//
	// - Requires a vault session and the vault right `change_metadata_structure`.
	// - An unknown ID fails with "Not found. <id>" (0x800408A4).
	rpc GetAsyncTask( GetAsyncTaskRequest ) returns ( GetAsyncTaskResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the newest asynchronous task of the vault and asks the server to queue pending tasks for
	// running now.
	//
	// - Requires a vault session and the vault right `change_metadata_structure`.
	// - When a task exists, the server queues the vault's pending tasks for running instead of
	//   waiting for its next scheduling round, on this server and, by broadcast, on the others.
	// - Use the returned ID as the starting point when waiting for background work (see the service
	//   overview).
	rpc QueueAndGetLatestAsyncTask( QueueAndGetLatestAsyncTaskRequest ) returns ( QueueAndGetLatestAsyncTaskResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Waits until the given asynchronous tasks have finished, then optionally returns a list of tasks.
	//
	// - **Blocks without a server-side time limit**: the server checks the tasks every two seconds
	//   until all are done. Set a deadline on the call. The wait is cancelled with an error when the
	//   server shuts down or the vault goes offline.
	// - A task counts as done when it has completed successfully or was cancelled. When a task was
	//   merged into a newer task, the server waits for the newer one. When a task fails, the call fails
	//   with the task's error. An unknown ID fails with "Not found. <id>".
	// - At most 50 tasks per call, and `tasks_request.max_count` at most 50; more fail with "The
	//   parameter is incorrect.".
	// - `tasks_request` is run after the wait, so its result lists the tasks that are still queued or
	//   running at that point. See the waiting recipe in the service overview.
	// - Requires a vault session and the vault right `change_metadata_structure`.
	rpc WaitForAsyncTaskCompletion( WaitForAsyncTaskCompletionRequest ) returns ( WaitForAsyncTaskCompletionResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets a page of asynchronous tasks, oldest or newest first, optionally only tasks in given
	// states.
	//
	// - Requires a vault session and the vault right `change_metadata_structure`.
	// - **Set `max_count` and `async_task_start`.** `max_count` 0 returns nothing. With `latest`, set
	//   `async_task_start` to -1 to start from the newest task; the default 0 returns nothing.
	// - With `latest`, a start ID and `filters`, the result also includes newer tasks into which
	//   matching older tasks were merged.
	// - `filters` with only unknown bits fails with "The parameter is incorrect. (Unknown filter)".
	rpc GetAsyncTasksRange( GetAsyncTasksRangeRequest ) returns ( GetAsyncTasksRangeResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the run state of a background operation, such as an external object type refresh.
	//
	// - Requires a vault session and the vault right `change_metadata_structure`.
	// - An unknown operation fails with "Not found.".
	rpc GetBackgroundOperationStatus( GetBackgroundOperationStatusRequest ) returns ( GetBackgroundOperationStatusResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Starts a background operation now, such as a full refresh of an external object type from its
	// external database.
	//
	// - **Starts a background operation and returns before it completes** (with
	//   `wait_until_started`, after it has started); follow it with
	//   [GetBackgroundOperationStatus](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetBackgroundOperationStatus)
	//   or [WaitForBackgroundOperationCompletion](mfiles:MFiles.IRPCBackgroundOperationsAdmin.WaitForBackgroundOperationCompletion).
	// - External object type refreshes are full refreshes. They fail when the object type's external
	//   connection is disabled; external location refreshes fail when the location is disabled.
	// - In a multi-server vault, a refresh may run on the server responsible for it instead of the
	//   one you called.
	// - Requires a vault session and the vault right `change_metadata_structure`.
	rpc StartBackgroundOperation( StartBackgroundOperationRequest ) returns ( StartBackgroundOperationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Waits until a background operation has finished, or stops it.
	//
	// - Returns immediately if the operation is not running. Otherwise blocks until it finishes; set
	//   a deadline on the call.
	// - With `force_stop`, the operation is asked to stop as soon as possible.
	// - Requires a vault session and the vault right `change_metadata_structure`.
	rpc WaitForBackgroundOperationCompletion( WaitForBackgroundOperationCompletionRequest ) returns ( WaitForBackgroundOperationCompletionResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of CheckAndRegisterMultiServerResponsibility.
message CheckAndRegisterMultiServerResponsibilityRequest {

	// ID of the operation to check.
	string operation_id = 1;
}

// The response of CheckAndRegisterMultiServerResponsibility.
message CheckAndRegisterMultiServerResponsibilityResponse {

	// Receives true if this server machine is responsible of requested operation.
	bool is_responsible = 1;
}

// The request of GetAsyncTasks.
message GetAsyncTasksRequest {
}

// The response of GetAsyncTasks.
message GetAsyncTasksResponse {

	// The tasks, newest first.
	repeated AsyncTask async_tasks = 1;
}

// The request of GetAsyncTask.
message GetAsyncTaskRequest {

	// The ID of the task.
	int64 async_task = 1;
}

// The response of GetAsyncTask.
message GetAsyncTaskResponse {

	// The task.
	AsyncTask async_task = 1;
}

// The request of QueueAndGetLatestAsyncTask.
message QueueAndGetLatestAsyncTaskRequest {
}

// The response of QueueAndGetLatestAsyncTask.
message QueueAndGetLatestAsyncTaskResponse {

	// True if the vault has at least one asynchronous task.
	bool is_available = 1;

	// The newest task (highest ID). Valid only if `is_available` is true.
	AsyncTask async_task = 2;
}

// A structure that specifies the request type for the WaitForAsyncTaskCompletion method.
message WaitForAsyncTaskCompletionRequest {

	// Obsolete. Set 0; a non-zero ID is waited for in addition to `async_tasks`.
	int64 obsolete_async_task = 1;

	// Optional. If set, the response carries the result of this [GetAsyncTasksRange](mfiles:MFiles.IRPCBackgroundOperationsAdmin.GetAsyncTasksRange) request, run after the wait. `max_count` must be at most 50.
	GetAsyncTasksRangeRequest tasks_request = 2;

	// The IDs of the tasks to wait for, at most 50.
	repeated int64 async_tasks = 3;
}

// A structure that specifies the response type for the WaitForAsyncTaskCompletion method.
message WaitForAsyncTaskCompletionResponse {

	// The result of `tasks_request`; unset if the request had none.
	GetAsyncTasksRangeResponse tasks_response = 1;
}

// A structure that specifies the request type for the WaitForAsyncTaskCompletion method.
message GetAsyncTasksRangeRequest {

	// The first task ID to return, or -1 to start from the newest (`latest` true) or the oldest (`latest` false) task.
	int64 async_task_start = 1;

	// The maximum number of tasks to return. 0 returns nothing.
	uint32 max_count = 2;

	// True to go from `async_task_start` towards older tasks (descending IDs), false to go towards newer tasks (ascending IDs).
	bool latest = 3;

	// The task states to include, as a sum of bit values: 1 queued, 2 running, 4 completed successfully, 8 cancelled, 16 failed. 0 includes all tasks.
	uint32 filters = 4;
}

// A structure that specifies the response type for the WaitForAsyncTaskCompletion method.
message GetAsyncTasksRangeResponse {

	// The tasks, in the order given by `latest`.
	repeated AsyncTask async_tasks = 1;
}

// A structure that specifies the request type for the corresponding method.
message GetBackgroundOperationStatusRequest {

	// The operation: `type`, and `id` (the object type ID or the external location ID for the refresh types).
	BackgroundOperationID background_operation_id = 1;
}

// A structure that specifies the response type for the corresponding method.
message GetBackgroundOperationStatusResponse {

	// The run state of the operation: running or not, last and next run, errors and progress.
	ScheduledJobRunInfo scheduled_job_run_info = 1;
}

// A structure that specifies the request type for the corresponding method.
message StartBackgroundOperationRequest {

	// The operation to start.
	BackgroundOperationID background_operation_id = 1;

	// True to signal a new start even if the operation is already running; false to leave a running operation alone.
	bool restart_if_already_running = 2;

	// True to return only after the operation has actually started. Has no effect if `restart_if_already_running` is false and the operation is already running.
	bool wait_until_started = 3;
}

// The response of StartBackgroundOperation.
message StartBackgroundOperationResponse {
}

// A structure that specifies the request type for the corresponding method.
message WaitForBackgroundOperationCompletionRequest {

	// The operation to wait for.
	BackgroundOperationID background_operation_id = 1;

	// True to stop the operation as soon as possible, false to let it finish.
	bool force_stop = 2;
}

// The response of WaitForBackgroundOperationCompletion.
message WaitForBackgroundOperationCompletionResponse {
}