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

// Lists, adds, changes, removes, starts and cancels scheduled jobs of the server or of a vault.
//
// Use this interface to add, remove and modify scheduled jobs.
//
// M-Files Admin uses this service for scheduled jobs (backups, vault copies, verification) and for
// the archiving and optimization jobs of a vault. A job is a
// [ScheduledJob](mfiles:MFiles.ScheduledJob): a `type`, the job details in `data`, an `is_enabled`
// flag and a `schedule`. Its state is a
// [ScheduledJobRunInfo](mfiles:MFiles.ScheduledJobRunInfo): whether it is running, the last and
// next run, errors and progress.
//
// **Two job lists.** The session decides which jobs a call sees; their IDs are separate.
//
// | Session | Jobs | Rights |
// | --- | --- | --- |
// | Server-level (`login_data.vault_guid` = null GUID) | Server jobs: backup, restore, copy vault, verify vault, recalculate property, migrate vault, encrypt file data, and optimize vault | Server right `manage_jobs` (system administrator server role) |
// | Vault session | The vault's jobs: archive objects, archive old versions, restore from archive, optimize vault | Vault rights `archive` and `restore_from_archive`, or `manage_scheduled_jobs`; optimize vault jobs need `manage_scheduled_jobs` |
//
// A server job cannot be handled in a vault session, and archiving jobs only in a session of their
// vault. A vault administrator therefore manages the vault's archiving and optimization jobs but
// not backups. Exceptions for server jobs: reading, starting and cancelling recalculate property
// jobs, and reading verify vault jobs, do not need `manage_jobs`. Archiving jobs also need a
// license that includes archiving. Missing rights fail with "Access denied.".
//
// Typical calls: [GetScheduledJobs](mfiles:MFiles.IRPCScheduledJobsAdmin.GetScheduledJobs) to list,
// [AddScheduledJob](mfiles:MFiles.IRPCScheduledJobsAdmin.AddScheduledJob) /
// [ModifyScheduledJob](mfiles:MFiles.IRPCScheduledJobsAdmin.ModifyScheduledJob) /
// [RemoveScheduledJob](mfiles:MFiles.IRPCScheduledJobsAdmin.RemoveScheduledJob) to maintain,
// [StartScheduledJob](mfiles:MFiles.IRPCScheduledJobsAdmin.StartScheduledJob) to run one now, then
// poll [GetScheduledJobRunInfo](mfiles:MFiles.IRPCScheduledJobsAdmin.GetScheduledJobRunInfo)
// until `is_running` is false.
//
// **Unset times.** In run info, "never" or "no next run" is the timestamp 1601-01-01T00:00:00Z,
// not an unset field.
service IRPCScheduledJobsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Scheduled jobs" };

	// Removes a scheduled job.
	//
	// - **Destructive.** The job definition is deleted; the job no longer runs.
	// - Rights depend on the job's type (see the service overview); an unknown ID fails with "Not
	//   found.".
	rpc RemoveScheduledJob( RemoveScheduledJobRequest ) returns ( RemoveScheduledJobResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Runs a scheduled job now, outside its schedule.
	//
	// - **Starts a background job and returns before it completes**; follow it with
	//   [GetScheduledJobRunInfo](mfiles:MFiles.IRPCScheduledJobsAdmin.GetScheduledJobRunInfo).
	// - Fails with "The job is already running." if it is running.
	// - Rights depend on the job's type (see the service overview).
	rpc StartScheduledJob( StartScheduledJobRequest ) returns ( StartScheduledJobResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Asks a running scheduled job to stop.
	//
	// - Sets the job's cancel flag and returns; the job stops asynchronously. Check
	//   `last_run_cancelled` with
	//   [GetScheduledJobRunInfo](mfiles:MFiles.IRPCScheduledJobsAdmin.GetScheduledJobRunInfo).
	// - Allowed also when the vault is offline, so that a vault's optimize job can be stopped.
	// - Requires `manage_jobs`, or the rights for the job's type (see the service overview). An
	//   unknown ID fails with "Not found.".
	rpc CancelScheduledJob( CancelScheduledJobRequest ) returns ( CancelScheduledJobResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Reads a block of a job output file, such as the summary of a restore from archive preview.
	//
	// - The `download_id` comes from the call that produced the file, for example
	//   `RestoreFromArchiveResponse.download_idsummary` of
	//   [RestoreFromArchive](mfiles:MFiles.IRPCVaultAdmin.RestoreFromArchive) with `preview_only`.
	// - Read from offset 0 onwards until a block is shorter than requested. The server then deletes
	//   the download session; it also deletes it when a read fails. An unknown or finished
	//   `download_id` fails with "Not found. (The specified download session ... does not exist.)".
	// - `block_size` is at most 4 MiB. Only the session that started the download can read it.
	// - Requires the vault rights `archive` and `restore_from_archive`, or `manage_scheduled_jobs`
	//   (in a server-level session, `manage_jobs`).
	rpc DownloadScheduledJobOutputFile_ReadBlock( DownloadScheduledJobOutputFile_ReadBlockRequest ) returns ( DownloadScheduledJobOutputFile_ReadBlockResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the run state of a scheduled job: running or not, last and next run, errors and progress.
	//
	// - Use it to poll a job after
	//   [StartScheduledJob](mfiles:MFiles.IRPCScheduledJobsAdmin.StartScheduledJob).
	// - Allowed also when the vault is offline. Requires `manage_jobs` or the rights for the job's
	//   type (see the service overview). An unknown ID fails with "Not found.".
	rpc GetScheduledJobRunInfo( GetScheduledJobRunInfoRequest ) returns ( GetScheduledJobRunInfoResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the scheduled jobs of the server (server-level session) or of the vault (vault session),
	// with their run state.
	//
	// - Returns only the jobs the caller has rights to; fails with "Access denied." if it has rights
	//   to none. Temporary jobs are not included.
	// - In a vault session, optimize vault jobs are returned only if the session was opened with
	//   `client_data.capabilities.vault_level_optimization_jobs` true.
	// - Allowed also when the vault is offline.
	rpc GetScheduledJobs( GetScheduledJobsRequest ) returns ( GetScheduledJobsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a scheduled job to the server or to the vault, depending on the job type.
	//
	// - `scheduled_job.type` and the session decide where the job goes and which rights it needs
	//   (see the service overview): a server job needs a server-level session; archiving jobs need a
	//   session of their vault.
	// - The server assigns the ID; `scheduled_job.id` is ignored.
	// - Takes effect immediately: an enabled job runs on its schedule.
	rpc AddScheduledJob( AddScheduledJobRequest ) returns ( AddScheduledJobResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Replaces the definition of an existing scheduled job.
	//
	// - The job is identified by `scheduled_job.id`; the whole definition is replaced.
	// - Rights depend on the job's type (see the service overview).
	rpc ModifyScheduledJob( ModifyScheduledJobRequest ) returns ( ModifyScheduledJobResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets one scheduled job and its run state.
	//
	// - Rights depend on the job's type (see the service overview). An unknown ID fails with "Not
	//   found.".
	rpc GetScheduledJob( GetScheduledJobRequest ) returns ( GetScheduledJobResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Resets the saved progress of an optimize vault job, so that its next run retries the failed
	// step or starts over.
	//
	// - Only for optimize vault jobs (`JOB_TYPE_OPTIMIZE_VAULT`); other job types fail with "The
	//   parameter is incorrect.". Fails with "The job is already running." while the job runs.
	// - Changes only what the next run does; it does not start the job.
	// - Allowed also when the vault is offline. Requires `manage_jobs` or `manage_scheduled_jobs` (see
	//   the service overview).
	rpc ResetScheduledJobProgress( ResetScheduledJobProgressRequest ) returns ( ResetScheduledJobProgressResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of RemoveScheduledJob.
message RemoveScheduledJobRequest {

	// The ID of the job to remove.
	int32 scheduled_job = 1;
}

// The response of RemoveScheduledJob.
message RemoveScheduledJobResponse {
}

// The request of StartScheduledJob.
message StartScheduledJobRequest {

	// The ID of the job to run.
	int32 scheduled_job = 1;
}

// The response of StartScheduledJob.
message StartScheduledJobResponse {
}

// The request of CancelScheduledJob.
message CancelScheduledJobRequest {

	// The ID of the job to cancel.
	int32 scheduled_job = 1;
}

// The response of CancelScheduledJob.
message CancelScheduledJobResponse {
}

// The request of DownloadScheduledJobOutputFile_ReadBlock.
message DownloadScheduledJobOutputFile_ReadBlockRequest {

	// The download session ID returned by the call that produced the file.
	int32 download_id = 1;

	// The number of bytes to read, at most 4194304.
	uint32 block_size = 2;

	// The byte offset to start reading from.
	int64 offset = 3;
}

// The response of DownloadScheduledJobOutputFile_ReadBlock.
message DownloadScheduledJobOutputFile_ReadBlockResponse {

	// The bytes read; shorter than `block_size` at the end of the file.
	bytes data = 1;
}

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

	// The ID of the job.
	int32 scheduled_job = 1;
}

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

	// The run state of the job.
	ScheduledJobRunInfo scheduled_job_run_info = 1;
}

// The request of GetScheduledJobs.
message GetScheduledJobsRequest {
}

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

	// The scheduled jobs.
	repeated ScheduledJob jobs = 1;

	// The run state of each job, at the same index as in `jobs`.
	repeated ScheduledJobRunInfo run_infos = 2;
}

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

	// The new job. `id` is ignored.
	ScheduledJob scheduled_job = 1;
}

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

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

	// The run state of the new job.
	ScheduledJobRunInfo run_info = 2;
}

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

	// The complete new definition of the job, with its `id`.
	ScheduledJob scheduled_job = 1;
}

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

	// The run state of the job after the change.
	ScheduledJobRunInfo run_info = 1;
}

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

	// The ID of the job.
	int32 scheduled_job = 1;
}

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

	// The job definition.
	ScheduledJob scheduled_job = 1;

	// The run state of the job.
	ScheduledJobRunInfo run_info = 2;
}

// A structure that specifies the request of the method that resets the resume progress of a scheduled job.
message ResetScheduledJobProgressRequest {

	// The ID of the optimize vault job.
	int32 scheduled_job = 1;

	// True to start over from the first step on the next run, false to retry the failed step.
	bool start_over = 2;
}

// The response of ResetScheduledJobProgress.
message ResetScheduledJobProgressResponse {
}