// 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 workflows: reads their full definitions with states and transitions, and adds,
// modifies and removes them.
//
// Use this interface to add, modify and delete workflows in a vault.
//
// This is the administrator's side of workflows. M-Files Admin calls it; applications that move
// objects through workflows read them with
// [GetWorkflowsForClient](mfiles:MFiles.IRPCObjectOperations.GetWorkflowsForClient) and
// [GetWorkflowStatesAndTransitions](mfiles:MFiles.IRPCObjectOperations.GetWorkflowStatesAndTransitions),
// which need no special rights and return what the caller may do (see
// [Workflows](https://developer.m-files.com/APIs/gRPC-API/concepts/workflows/)).
//
// | | Vault API (read side) | This service |
// | --- | --- | --- |
// | Data | names, states and the transitions the user may take | [WorkflowAdmin](mfiles:MFiles.WorkflowAdmin): states with their actions and conditions, transitions with their permissions, triggers and signatures, the workflow ACL, aliases and diagram layout |
// | Rights | none | `read_all_metadata_structure` to read, `manage_workflows` to write |
//
// - **Session and rights.** Every method requires a vault session.
//   [GetWorkflows](mfiles:MFiles.IRPCWorkflowsAdmin.GetWorkflows) needs the vault right
//   `read_all_metadata_structure` (a normal user gets "Access denied."). The write methods
//   need `manage_workflows` and `license_allows_modifications`. Setting or changing VBScript code in
//   states and transitions also needs a code-execution right (see
//   [AddWorkflow](mfiles:MFiles.IRPCWorkflowsAdmin.AddWorkflow)).
// - **Calls**: [GetWorkflows](mfiles:MFiles.IRPCWorkflowsAdmin.GetWorkflows), then
//   [AddWorkflow](mfiles:MFiles.IRPCWorkflowsAdmin.AddWorkflow) or
//   [ModifyWorkflow](mfiles:MFiles.IRPCWorkflowsAdmin.ModifyWorkflow) with a complete
//   [WorkflowAdmin](mfiles:MFiles.WorkflowAdmin), and
//   [RemoveWorkflow](mfiles:MFiles.IRPCWorkflowsAdmin.RemoveWorkflow) or
//   [RemoveWorkflows](mfiles:MFiles.IRPCWorkflowsAdmin.RemoveWorkflows).
// - **New states and transitions** get negative placeholder IDs in the request (-1, -2, ...);
//   transitions refer to new states by these placeholders. The response contains the workflow as
//   stored, with real IDs.
// - **Metadata structure version.** Every successful add, modify and remove increments the vault's metadata
//   version when it commits; clients that cache workflows reload them. The methods do not send the
//   `mfiles-metadata-version-bin` trailer; see
//   [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/).
service IRPCWorkflowsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Workflow administration" };

	// Deletes a workflow with its states and transitions.
	//
	// - Requires `manage_workflows` and `license_allows_modifications`.
	// - Classes that used the workflow as their workflow no longer refer to it.
	// - An unknown ID fails with "Not found.". Increments the metadata structure version.
	rpc RemoveWorkflow( RemoveWorkflowRequest ) returns ( RemoveWorkflowResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes several workflows in one transaction.
	//
	// - Same rules as [RemoveWorkflow](mfiles:MFiles.IRPCWorkflowsAdmin.RemoveWorkflow); if one
	//   workflow cannot be removed, none are.
	rpc RemoveWorkflows( RemoveWorkflowsRequest ) returns ( RemoveWorkflowsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Creates a workflow with its states and transitions.
	//
	// - Requires `manage_workflows` and `license_allows_modifications`.
	// - VBScript code in states (actions, pre- and postconditions) and transitions also requires the
	//   server right `run_code`; code with a valid signature needs only the vault right
	//   `run_signed_code`.
	// - The session language must be the vault's default language; otherwise the call fails with
	//   "Not implemented.".
	// - Fails when another workflow has the same name (case-insensitive).
	// - Increments the metadata structure version.
	rpc AddWorkflow( AddWorkflowRequest ) returns ( AddWorkflowResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Saves a changed workflow with its states and transitions.
	//
	// - Same rights, code rules and language rule as
	//   [AddWorkflow](mfiles:MFiles.IRPCWorkflowsAdmin.AddWorkflow).
	// - Send the complete workflow: start from
	//   [GetWorkflows](mfiles:MFiles.IRPCWorkflowsAdmin.GetWorkflows). Existing states and transitions
	//   keep their IDs; new ones use negative placeholder IDs.
	// - Increments the metadata structure version.
	rpc ModifyWorkflow( ModifyWorkflowRequest ) returns ( ModifyWorkflowResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the full administrative definitions of all workflows.
	//
	// - Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
	// - Returned 4 workflows in the Sample Vault. The order is undefined.
	rpc GetWorkflows( GetWorkflowsRequest ) returns ( GetWorkflowsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of RemoveWorkflow.
message RemoveWorkflowRequest {

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

// The response of RemoveWorkflow.
message RemoveWorkflowResponse {
}

// The request of RemoveWorkflows.
message RemoveWorkflowsRequest {

	// The IDs of workflows to delete.
	repeated int32 workflow_ids = 1;
}

// The response of RemoveWorkflows.
message RemoveWorkflowsResponse {
}

// The request of AddWorkflow.
message AddWorkflowRequest {

	// The new workflow. `workflow.workflow.id` is ignored; give the states and transitions negative placeholder IDs.
	WorkflowAdmin workflow = 1;
}

// The response of AddWorkflow.
message AddWorkflowResponse {

	// The workflow as stored, with real IDs for the workflow, its states and its transitions.
	WorkflowAdmin workflow_result = 1;
}

// The request of ModifyWorkflow.
message ModifyWorkflowRequest {

	// The complete new workflow; `workflow.workflow.id` identifies it.
	WorkflowAdmin workflow = 1;
}

// The response of ModifyWorkflow.
message ModifyWorkflowResponse {

	// The workflow as stored, with real IDs for new states and transitions.
	WorkflowAdmin workflow_result = 1;
}

// The request of GetWorkflows.
message GetWorkflowsRequest {
}

// The response of GetWorkflows.
message GetWorkflowsResponse {

	// One [WorkflowAdmin](mfiles:MFiles.WorkflowAdmin) per workflow.
	repeated WorkflowAdmin workflow_results = 1;
}