// 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 "google/protobuf/timestamp.proto";
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_";

// Manages the vault's exported data sets: the definitions of the vault data that M-Files Reporting
// Data Services exports to a reporting database.
//
// MFAdmin uses this interface to manage the data set configuration.
//
// M-Files Admin uses this service for the reporting and data export settings of a vault. An
// exported data set ([ExportedDataSetAdmin](mfiles:MFiles.ExportedDataSetAdmin)) names the object
// types, properties and filters to export, a schedule, and the OLE DB connection string of the
// target database. M-Files Reporting Data Services runs the exports; this service only stores the
// definitions, requests runs, and reads their status.
//
// - **Definitions**: [GetExportedDataSetsAdmin](mfiles:MFiles.IRPCExportedDataSetsAdmin.GetExportedDataSetsAdmin),
//   [AddNewExportedDataSet](mfiles:MFiles.IRPCExportedDataSetsAdmin.AddNewExportedDataSet),
//   [ModifyExportedDataSet](mfiles:MFiles.IRPCExportedDataSetsAdmin.ModifyExportedDataSet),
//   [RemoveExportedDataSet](mfiles:MFiles.IRPCExportedDataSetsAdmin.RemoveExportedDataSet).
// - **Runs**: [TriggerExportedDataSetExecution](mfiles:MFiles.IRPCExportedDataSetsAdmin.TriggerExportedDataSetExecution),
//   [CancelExportedDataSetExecution](mfiles:MFiles.IRPCExportedDataSetsAdmin.CancelExportedDataSetExecution),
//   [GetExportedDataSetExecutionStatus](mfiles:MFiles.IRPCExportedDataSetsAdmin.GetExportedDataSetExecutionStatus).
// - **Report access account**:
//   [GetReportAccessCredentialsAdmin](mfiles:MFiles.IRPCExportedDataSetsAdmin.GetReportAccessCredentialsAdmin),
//   [SetReportAccessCredentials](mfiles:MFiles.IRPCExportedDataSetsAdmin.SetReportAccessCredentials).
//
// **Rights.** All methods need a vault session and a server license that includes the reporting
// module ("This operation requires the reporting module." otherwise), except that
// [GetExportedDataSetsAdmin](mfiles:MFiles.IRPCExportedDataSetsAdmin.GetExportedDataSetsAdmin)
// returns an empty list without it. Most methods need the vault right `see_all_objects`. The
// connection string makes the server connect to a data source with its own service account, so
// setting a new one needs the server right `run_code`, which a vault administrator normally does
// not have (see [AddNewExportedDataSet](mfiles:MFiles.IRPCExportedDataSetsAdmin.AddNewExportedDataSet)).
// Users without administrator rights can request a run with
// [TriggerExportedDataSetRefresh](mfiles:MFiles.IRPCExportedDataSets.TriggerExportedDataSetRefresh)
// if they have the vault right `trigger_data_export`.
service IRPCExportedDataSetsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Exported data set administration" };

	// Adds an exported data set.
	//
	// - Requires a vault session, the vault right `see_all_objects`, and the server right `run_code`:
	//   a caller without `run_code` cannot set a connection string, so the call fails with "Access
	//   denied." for it.
	// - The server assigns the ID; `dataset.id` is ignored.
	rpc AddNewExportedDataSet( AddNewExportedDataSetRequest ) returns ( AddNewExportedDataSetResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Replaces the definition of an exported data set.
	//
	// - The data set is identified by `expdataset.dataset.id`; the whole definition is replaced.
	// - Requires a vault session and the vault right `see_all_objects`. Without the server right
	//   `run_code`, the connection string may change only in its credentials, and only with the vault
	//   right `run_signed_code` (part of full control); pointing it to another data source fails with
	//   "Access denied.".
	rpc ModifyExportedDataSet( ModifyExportedDataSetRequest ) returns ( ModifyExportedDataSetResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Removes an exported data set.
	//
	// - **Destructive.** Deletes the definition; already exported data in the target database is not
	//   touched by this call.
	// - Requires a vault session and the vault right `see_all_objects`. An unknown ID fails with
	//   "Not found.".
	rpc RemoveExportedDataSet( RemoveExportedDataSetRequest ) returns ( RemoveExportedDataSetResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Requests an immediate export run of an exported data set.
	//
	// - **Requests a background run and returns at once**: the server records the request and M-Files
	//   Reporting Data Services runs the export. Follow it with
	//   [GetExportedDataSetExecutionStatus](mfiles:MFiles.IRPCExportedDataSetsAdmin.GetExportedDataSetExecutionStatus).
	// - Fails when the data set is disabled. An unknown ID fails with "Not found.".
	// - Requires a vault session and the vault right `see_all_objects`.
	rpc TriggerExportedDataSetExecution( TriggerExportedDataSetExecutionRequest ) returns ( TriggerExportedDataSetExecutionResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Requests that a running export of an exported data set stops.
	//
	// - Records the cancel request and returns; M-Files Reporting Data Services stops the run.
	// - Fails when the data set is disabled. An unknown ID fails with "Not found.".
	// - Requires a vault session and the vault right `see_all_objects`.
	rpc CancelExportedDataSetExecution( CancelExportedDataSetExecutionRequest ) returns ( CancelExportedDataSetExecutionResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the progress and status of the latest export run of an exported data set.
	//
	// - Requires a vault session and the vault right `see_all_objects`. An unknown ID fails with
	//   "Not found.".
	rpc GetExportedDataSetExecutionStatus( GetExportedDataSetExecutionStatusRequest ) returns ( GetExportedDataSetExecutionStatusResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Sets the account that is used to access reports generated from the exported data.
	//
	// - Requires a vault session and the vault rights `manage_users` and `see_all_objects`.
	// - `encrypted_password` must be encrypted with the server's public key
	//   ([GetPublicKey](mfiles:MFiles.IRPCLogin.GetPublicKey)), as M-Files Admin does.
	rpc SetReportAccessCredentials( SetReportAccessCredentialsRequest ) returns ( SetReportAccessCredentialsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the account that is used to access reports generated from the exported data.
	//
	// - Requires a vault session and the vault right `see_all_objects` (a normal user is
	//   denied).
	// - The password is not returned in clear text: `encrypted_password` is encrypted with the
	//   server's public key.
	// - When no account has been set, `type` is `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` and `account` is
	//   empty.
	rpc GetReportAccessCredentialsAdmin( GetReportAccessCredentialsAdminRequest ) returns ( GetReportAccessCredentialsAdminResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all exported data sets of the vault.
	//
	// - Requires only a vault session: any user can call it. The
	//   `database_connection_string` of each data set is empty unless the caller has the vault right
	//   `see_all_objects`.
	// - Returns an empty list when the server license does not include the reporting module.
	rpc GetExportedDataSetsAdmin( GetExportedDataSetsAdminRequest ) returns ( GetExportedDataSetsAdminResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of AddNewExportedDataSet.
message AddNewExportedDataSetRequest {

	// The new data set. `dataset.id` is ignored.
	ExportedDataSetAdmin expdataset = 1;
}

// The response of AddNewExportedDataSet.
message AddNewExportedDataSetResponse {

	// The stored data set, with its new `dataset.id`.
	ExportedDataSetAdmin result = 1;
}

// The request of ModifyExportedDataSet.
message ModifyExportedDataSetRequest {

	// The complete new definition, with the `dataset.id` of the data set to change.
	ExportedDataSetAdmin expdataset = 1;
}

// The response of ModifyExportedDataSet.
message ModifyExportedDataSetResponse {
}

// The request of RemoveExportedDataSet.
message RemoveExportedDataSetRequest {

	// The ID of the data set to remove.
	int32 id = 1;
}

// The response of RemoveExportedDataSet.
message RemoveExportedDataSetResponse {
}

// The request of TriggerExportedDataSetExecution.
message TriggerExportedDataSetExecutionRequest {

	// The ID of the data set to export.
	int32 id = 1;
}

// The response of TriggerExportedDataSetExecution.
message TriggerExportedDataSetExecutionResponse {
}

// The request of CancelExportedDataSetExecution.
message CancelExportedDataSetExecutionRequest {

	// The ID of the data set whose run to cancel.
	int32 id = 1;
}

// The response of CancelExportedDataSetExecution.
message CancelExportedDataSetExecutionResponse {
}

// The request of GetExportedDataSetExecutionStatus.
message GetExportedDataSetExecutionStatusRequest {

	// The ID of the data set.
	int32 id = 1;
}

// The response of GetExportedDataSetExecutionStatus.
message GetExportedDataSetExecutionStatusResponse {

	// The progress of the current run, 0-100.
	int32 progress_percent = 1;

	// The current status; the error message if the run failed.
	string status_explanation = 2;

	// When the status was last updated.
	google.protobuf.Timestamp status_time = 3;
}

// The request of SetReportAccessCredentials.
message SetReportAccessCredentialsRequest {

	// The account: `type`, `account` (for example `DOMAIN\user`), and `encrypted_password`.
	Impersonation utf8szimpersonation = 1;
}

// The response of SetReportAccessCredentials.
message SetReportAccessCredentialsResponse {
}

// The request of GetReportAccessCredentialsAdmin.
message GetReportAccessCredentialsAdminRequest {
}

// The response of GetReportAccessCredentialsAdmin.
message GetReportAccessCredentialsAdminResponse {

	// The report access account.
	Impersonation impersonation = 1;
}

// The request of GetExportedDataSetsAdmin.
message GetExportedDataSetsAdminRequest {
}

// The response of GetExportedDataSetsAdmin.
message GetExportedDataSetsAdminResponse {

	// The exported data sets.
	repeated ExportedDataSetAdmin results = 1;
}