// 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 the vault's external sources: file folders and mail boxes from which the server
// imports or links content.
//
// Use this interface to add, modify and delete external locations in a vault.
//
// An external location is a definition of a local or remote location
// that contains files and folders. M-Files includes the files in such
// a location in the document vault and monitors the location for
// file additions and removals.
//
// An external location ([ExternalLocation](mfiles:MFiles.ExternalLocation)) is a file source (a
// folder the server imports files from, or links them in place) or a mail source (a mail box the
// server imports messages from, see `MailProtocol`). The server's background monitor checks each
// location every `update_interval` seconds. M-Files Admin calls this service. The locations are
// also the items of the built-in value list 5.
//
// - **Session and rights.** Every method requires a vault session and the vault right
//   `manage_external_locations`; a normal user gets "Access denied.".
//   [AddExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.AddExternalLocation) and
//   [ModifyExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.ModifyExternalLocation) of a
//   file source also require the server right `run_code` (system administrator), because the server
//   reads that folder under its own account. Mail sources need only the vault right.
// - **Calls**: [GetExternalLocations](mfiles:MFiles.IRPCExternalLocationsAdmin.GetExternalLocations),
//   [AddExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.AddExternalLocation),
//   [ModifyExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.ModifyExternalLocation),
//   [RemoveExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.RemoveExternalLocation),
//   [RefreshExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.RefreshExternalLocation)
//   (check now) and
//   [ImportFilesFromLinkedLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.ImportFilesFromLinkedLocation)
//   (turn linked files into imported ones).
service IRPCExternalLocationsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "External locations" };

	// Deletes an external location, optionally destroying the documents whose files are linked to it.
	//
	// - With `destroy_docs_with_linked_files` true, **destroys every document that has a file linked to
	//   the location** before deleting it. This cannot be undone.
	// - With it false, the call fails while documents with files linked to the location exist.
	// - Requires `manage_external_locations`.
	rpc RemoveExternalLocation( RemoveExternalLocationRequest ) returns ( RemoveExternalLocationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Checks the location now instead of waiting for the next automatic round.
	//
	// - Tests access to the location first and fails if the location is disabled or cannot be reached.
	// - Starts the refresh as a background operation and returns once it has started, not when it has
	//   finished.
	// - Requires `manage_external_locations`.
	rpc RefreshExternalLocation( RefreshExternalLocationRequest ) returns ( RefreshExternalLocationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Creates an external location.
	//
	// - Requires `manage_external_locations`; a file source also requires the server right `run_code`.
	// - For a mail source without `run_code`, `update_interval` must be at least 60 seconds.
	// - A file source cannot both link files (`file_source.link_files`) and convert them to
	//   searchable PDF (`file_source.convert_to_searchable_pdf`): invalid-argument error.
	// - With `test_access` true, the server connects to the location and rolls the addition back if
	//   that fails. With false, a location that does not work yet (for example a mail server that is
	//   down) can be saved.
	rpc AddExternalLocation( AddExternalLocationRequest ) returns ( AddExternalLocationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Saves a changed external location.
	//
	// - Same rights and rules as
	//   [AddExternalLocation](mfiles:MFiles.IRPCExternalLocationsAdmin.AddExternalLocation).
	// - `test_access` works as in AddExternalLocation; with false you can, for example, turn off
	//   automatic monitoring of a mail server that is down.
	rpc ModifyExternalLocation( ModifyExternalLocationRequest ) returns ( ModifyExternalLocationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all external locations of the vault.
	//
	// - Requires `manage_external_locations`; a normal user gets "Access denied.".
	// - Account passwords are not returned, and the OAuth client secret of mail sources is removed.
	// - Returned 4 locations in the Sample Vault, 3 file sources and 1 mail source.
	rpc GetExternalLocations( GetExternalLocationsRequest ) returns ( GetExternalLocationsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Converts a file source that links files into one that imports them, and starts importing.
	//
	// - Turns off `file_source.link_files` and automatic monitoring, saves the location, and starts the
	//   import as a background operation; returns before it finishes.
	// - Only for enabled file sources: a mail source fails with an invalid-argument error.
	// - Restarts the server's external file monitor: running checks of all locations stop, and
	//   automatic checks resume in about two minutes.
	// - Requires `manage_external_locations`.
	rpc ImportFilesFromLinkedLocation( ImportFilesFromLinkedLocationRequest ) returns ( ImportFilesFromLinkedLocationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of RemoveExternalLocation.
message RemoveExternalLocationRequest {

	// The ID of the external location to remove.
	int32 id = 1;

	// True to destroy all documents that contain files linked to the external location being removed.
	bool destroy_docs_with_linked_files = 2;
}

// The response of RemoveExternalLocation.
message RemoveExternalLocationResponse {
}

// The request of RefreshExternalLocation.
message RefreshExternalLocationRequest {

	// The ID of the external location to refresh.
	int32 id = 1;
}

// The response of RefreshExternalLocation.
message RefreshExternalLocationResponse {
}

// The request of AddExternalLocation.
message AddExternalLocationRequest {

	// The new location. `id` is ignored and assigned by the server.
	ExternalLocation json_ext_loc = 1;

	// True to test access to the external location before accepting the changes.
	bool test_access = 2;
}

// The response of AddExternalLocation.
message AddExternalLocationResponse {

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

// The request of ModifyExternalLocation.
message ModifyExternalLocationRequest {

	// The complete new location; `id` identifies it.
	ExternalLocation json_ext_loc = 1;

	// True to test access to the external location before accepting the changes.
	bool test_access = 2;
}

// The response of ModifyExternalLocation.
message ModifyExternalLocationResponse {
}

// The request of GetExternalLocations.
message GetExternalLocationsRequest {
}

// The response of GetExternalLocations.
message GetExternalLocationsResponse {

	// One [ExternalLocation](mfiles:MFiles.ExternalLocation) per location.
	repeated ExternalLocation json_ext_loc_array = 1;
}

// The request of ImportFilesFromLinkedLocation.
message ImportFilesFromLinkedLocationRequest {

	// The ID of the file source.
	int32 id = 1;
}

// The response of ImportFilesFromLinkedLocation.
message ImportFilesFromLinkedLocationResponse {

	// The location as saved, with linking and automatic monitoring off.
	ExternalLocation json_ext_loc = 1;
}