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

// Reads the exported data sets of the vault and reports their export status (M-Files Reporting).
//
// An exported data set describes which objects and properties M-Files Reporting copies from the
// vault to an external reporting database. The data sets are created and changed with the
// administration service [IRPCExportedDataSetsAdmin](mfiles:MFiles.IRPCExportedDataSetsAdmin);
// this service lets a vault session read them, start an export and follow its progress.
//
// - **Read the data sets**:
//   [GetExportedDataSets](mfiles:MFiles.IRPCExportedDataSets.GetExportedDataSets),
//   [GetExportedDataSet](mfiles:MFiles.IRPCExportedDataSets.GetExportedDataSet).
// - **Start an export now** and watch it:
//   [TriggerExportedDataSetRefresh](mfiles:MFiles.IRPCExportedDataSets.TriggerExportedDataSetRefresh),
//   then [GetDataSetExportingStatusBasic](mfiles:MFiles.IRPCExportedDataSets.GetDataSetExportingStatusBasic).
// - **Used by the export process itself**:
//   [GetDataSetAuxiliaryExecutionControlState](mfiles:MFiles.IRPCExportedDataSets.GetDataSetAuxiliaryExecutionControlState),
//   [GetDataSetExportingReferenceTimestamp](mfiles:MFiles.IRPCExportedDataSets.GetDataSetExportingReferenceTimestamp)
//   and [UpdateExportedDataSetExecutionStatus](mfiles:MFiles.IRPCExportedDataSets.UpdateExportedDataSetExecutionStatus).
//   Applications rarely need them.
//
// **Prerequisites.** Every method needs a vault session. All methods except
// [GetDataSetExportingReferenceTimestamp](mfiles:MFiles.IRPCExportedDataSets.GetDataSetExportingReferenceTimestamp)
// need the Reporting module in the server or vault license; without it they fail with a "no
// license for reporting" error, except
// [GetExportedDataSets](mfiles:MFiles.IRPCExportedDataSets.GetExportedDataSets), which returns an
// empty list. Data set IDs that do not exist fail with "Not found.".
//
// The objects and values that an export reads are available to any session through
// [IRPCDataExport](mfiles:MFiles.IRPCDataExport).
service IRPCExportedDataSets {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Exported data sets" };

	// Gets when an export of the data set was last requested or cancelled by hand. Used by the export
	// process.
	//
	// - Used by the M-Files Reporting export process to notice manual export and cancel requests;
	//   applications rarely call it.
	// - Requires a vault session and the Reporting module in the license. An unknown ID fails with
	//   "Not found.".
	rpc GetDataSetAuxiliaryExecutionControlState( GetDataSetAuxiliaryExecutionControlStateRequest ) returns ( GetDataSetAuxiliaryExecutionControlStateResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Stores the progress of an export. Reserved for the M-Files Reporting export process.
	//
	// - The server accepts the call only from a session of a local system administrator of the
	//   server machine. Other sessions, including vault administrators connected over gRPC, get
	//   "Access denied.".
	// - Fails if the data set is disabled.
	rpc UpdateExportedDataSetExecutionStatus( UpdateExportedDataSetExecutionStatusRequest ) returns ( UpdateExportedDataSetExecutionStatusResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Asks for an export of the data set to start now, outside its schedule.
	//
	// - Requires the vault right `trigger_data_export` and the Reporting module in the license.
	// - Fails if the data set is disabled, and with "Not found." for an unknown ID.
	// - The call only records the time of the request (returned as `last_manual_execution_triggered`
	//   by [GetDataSetAuxiliaryExecutionControlState](mfiles:MFiles.IRPCExportedDataSets.GetDataSetAuxiliaryExecutionControlState));
	//   the export process notices it and runs the export. Follow the progress with
	//   [GetDataSetExportingStatusBasic](mfiles:MFiles.IRPCExportedDataSets.GetDataSetExportingStatusBasic).
	// - Cancel a running export with the administration service
	//   ([CancelExportedDataSetExecution](mfiles:MFiles.IRPCExportedDataSetsAdmin.CancelExportedDataSetExecution)).
	rpc TriggerExportedDataSetRefresh( TriggerExportedDataSetRefreshRequest ) returns ( TriggerExportedDataSetRefreshResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether a data set is being exported right now and when its export status last changed.
	//
	// - Requires a vault session and the Reporting module in the license. Fails if the data set is
	//   disabled, and with "Not found." for an unknown ID.
	// - `exporting` is true while the export process reports progress (0-100) for the data set, and
	//   false once it has reported that the export is not running.
	// - Compare `latest_activity` with `current` (both server time) to see how recent the status is.
	rpc GetDataSetExportingStatusBasic( GetDataSetExportingStatusBasicRequest ) returns ( GetDataSetExportingStatusBasicResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the current server time, as the reference time for data set synchronization.
	//
	// - Requires a vault session. Does not need the Reporting module.
	rpc GetDataSetExportingReferenceTimestamp( GetDataSetExportingReferenceTimestampRequest ) returns ( GetDataSetExportingReferenceTimestampResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets one exported data set by ID.
	//
	// - Requires a vault session and the Reporting module in the license. An unknown ID fails with
	//   "Not found.".
	// - `database_connection_string` is empty unless the user has the vault right `see_all_objects`.
	rpc GetExportedDataSet( GetExportedDataSetRequest ) returns ( GetExportedDataSetResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all exported data sets of the vault.
	//
	// - Requires a vault session; no special vault rights.
	// - Returns an empty list when the license does not include the Reporting module.
	// - `database_connection_string` is empty unless the user has the vault right `see_all_objects`
	//   ([VaultAccess](mfiles:MFiles.VaultAccess)).
	rpc GetExportedDataSets( GetExportedDataSetsRequest ) returns ( GetExportedDataSetsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of GetDataSetAuxiliaryExecutionControlState.
message GetDataSetAuxiliaryExecutionControlStateRequest {

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

// The response of GetDataSetAuxiliaryExecutionControlState.
message GetDataSetAuxiliaryExecutionControlStateResponse {

	// When an export was last requested with [TriggerExportedDataSetRefresh](mfiles:MFiles.IRPCExportedDataSets.TriggerExportedDataSetRefresh) or the administration service. Unset if never.
	google.protobuf.Timestamp last_manual_execution_triggered = 1;

	// When an export was last cancelled. Unset if never.
	google.protobuf.Timestamp last_manual_execution_cancelled = 2;

	// The current server time, to compare the timestamps with.
	google.protobuf.Timestamp current = 3;
}

// The request of UpdateExportedDataSetExecutionStatus.
message UpdateExportedDataSetExecutionStatusRequest {

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

	// The progress of the export, 0-100, or -1 when the export is not running.
	int32 progress_percent = 2;

	// A description of the current state; the error message if the export failed.
	string status_explanation = 3;
}

// The response of UpdateExportedDataSetExecutionStatus.
message UpdateExportedDataSetExecutionStatusResponse {
}

// The request of TriggerExportedDataSetRefresh.
message TriggerExportedDataSetRefreshRequest {

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

// The response of TriggerExportedDataSetRefresh.
message TriggerExportedDataSetRefreshResponse {
}

// The request of GetDataSetExportingStatusBasic.
message GetDataSetExportingStatusBasicRequest {

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

// The response of GetDataSetExportingStatusBasic.
message GetDataSetExportingStatusBasicResponse {

	// True if the data set is being exported.
	bool exporting = 1;

	// The current server time.
	google.protobuf.Timestamp current = 2;

	// When the export process last updated the status of the data set. Unset if it never has.
	google.protobuf.Timestamp latest_activity = 3;
}

// The request of GetDataSetExportingReferenceTimestamp.
message GetDataSetExportingReferenceTimestampRequest {
}

// The response of GetDataSetExportingReferenceTimestamp.
message GetDataSetExportingReferenceTimestampResponse {

	// The current server time.
	google.protobuf.Timestamp current = 1;
}

// The request of GetExportedDataSet.
message GetExportedDataSetRequest {

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

// The response of GetExportedDataSet.
message GetExportedDataSetResponse {

	// The exported data set. See [ExportedDataSet](mfiles:MFiles.ExportedDataSet).
	ExportedDataSet pexpdataset = 1;
}

// The request of GetExportedDataSets.
message GetExportedDataSetsRequest {
}

// The response of GetExportedDataSets.
message GetExportedDataSetsResponse {

	// The exported data sets. See [ExportedDataSet](mfiles:MFiles.ExportedDataSet).
	repeated ExportedDataSet results = 1;
}