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

// An interface for working with electronic signatures.
//
// Administrative repair operations for electronic signatures that are stored as separate signature
// objects. Users sign by running a workflow state transition that requires an electronic
// signature; these two methods only add placeholder signatures to an object or detach signatures
// from it, for example to fix an object whose signatures are out of step with its workflow.
//
// - [AddEmptyElectronicSignature](mfiles:MFiles.IRPCElectronicSignatures.AddEmptyElectronicSignature)
//   creates unsigned (empty) signature objects for the signatures that the object's workflow
//   defines.
// - [DisconnectElectronicSignature](mfiles:MFiles.IRPCElectronicSignatures.DisconnectElectronicSignature)
//   removes signatures from the object, optionally marking them invalidated.
//
// Prerequisites shared by both methods:
//
// - The caller needs the vault rights `license_allows_modifications`, `see_all_objects` and
//   `edit_and_delete_all_objects` ([VaultAccess](mfiles:MFiles.VaultAccess)). Normal users get
//   "Access denied.".
// - The vault must have the metadata structure for separate signature objects: an object type
//   with the alias `M-Files.QMS.Signature.ObjectType` and property definitions such as
//   `M-Files.QMS.Signatures` (the object's reference to its signatures),
//   `M-Files.QMS.Signature.Identifier`, `M-Files.QMS.Signature.Signer`,
//   `M-Files.QMS.Signature.Reason` and `M-Files.QMS.Signature.Meaning`. Without it the calls fail
//   with "Not found." naming the missing alias.
// - `obj_ver` must name a specific version (`OBJ_VER_VERSION_TYPE_SPECIFIC`); the latest-version
//   form fails with "The parameter is incorrect.".
// - A signature is identified by the `signature_identifier` of the state transition that requires
//   it (`StateTransition.signature_settings.signature_identifier`, see
//   [ElectronicSignatureSettings](mfiles:MFiles.ElectronicSignatureSettings)).
//
// Both methods update the object's signatures property like a property change and return the
// object after the change.
service IRPCElectronicSignatures {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Electronic signatures" };

	// Adds empty (unsigned) separate signature objects to an object for one signature, or for all
	// signatures that its workflow requires.
	//
	// - Requires the vault rights listed in the service overview, and read and edit access to the
	//   object.
	// - The object must have a workflow; otherwise the call fails because the Workflow property is
	//   not set.
	// - With an empty `signature_identifier_can_be_null`, the server adds a signature for every state
	//   transition of the object's workflow whose signature settings are required and stored as a
	//   separate signature object. With an identifier, it adds only that signature; an identifier that
	//   no transition of the workflow uses fails with "Not found.", and one used by several
	//   transitions fails as ambiguous.
	// - A signature that the object already references is not added again.
	rpc AddEmptyElectronicSignature( AddEmptyElectronicSignatureRequest ) returns ( AddEmptyElectronicSignatureResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Removes one signature, or all signatures, from an object's signature references, optionally
	// invalidating the removed signature objects.
	//
	// - Requires the vault rights listed in the service overview.
	// - With `invalidate` false, the signature objects are only detached from the object. With
	//   `invalidate` true, they are also marked invalidated.
	rpc DisconnectElectronicSignature( DisconnectElectronicSignatureRequest ) returns ( DisconnectElectronicSignatureResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of AddEmptyElectronicSignature.
message AddEmptyElectronicSignatureRequest {

	// The object version to update. Must be a specific version.
	ObjVer obj_ver = 1;

	// The signature identifier of one state transition, or empty to add all required signatures of the object's workflow.
	string signature_identifier_can_be_null = 2;
}

// The response of AddEmptyElectronicSignature.
message AddEmptyElectronicSignatureResponse {

	// The object after the operation.
	ExtObjectInfo ext_obj_info = 1;

	// Other objects that the server updated during the operation.
	repeated ObjectVersionEx updated_objects = 2;
}

// The request of DisconnectElectronicSignature.
message DisconnectElectronicSignatureRequest {

	// The object version to update. Must be a specific version.
	ObjVer obj_ver = 1;

	// The signature identifier to remove, or empty to remove all signatures of the object.
	string signature_identifier_can_be_null = 2;

	// True to also mark the removed signature objects invalidated.
	bool invalidate = 3;
}

// The response of DisconnectElectronicSignature.
message DisconnectElectronicSignatureResponse {

	// The object after the operation.
	ExtObjectInfo ext_obje_info = 1;

	// Other objects that the server updated during the operation.
	repeated ObjectVersionEx updated_objects = 2;
}