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

// Manages notification rules: which events on which objects send the user a notification.
//
// A notification rule ([NotificationRule](mfiles:MFiles.NotificationRule)) combines a filter
// (`object_filter`, search conditions), the events to watch (`subscriptions`, such as
// `EVENT_TYPE_OBJECT_CREATED` or `EVENT_TYPE_OBJECT_CHANGED`) and delivery options (`options`).
// Notifications are sent by e-mail, and only when notifications are enabled on the server and in
// the vault and the user has not turned them off (see
// [GetNotificationConfiguration](mfiles:MFiles.IRPCEvents.GetNotificationConfiguration)).
//
// There are two kinds of rules:
//
// | Kind | `is_common` | Who manages it | Who it notifies |
// | --- | --- | --- | --- |
// | Private | false | users with the vault right `manage_private_notification_rules` | the owner |
// | Common | true | users with the vault right `manage_common_notification_rules` | the users and groups in `recipients` |
//
// Typical use:
//
// 1. [GetNotificationRules](mfiles:MFiles.IRPCNotificationRules.GetNotificationRules) to list the
//    rules that apply to the caller.
// 2. [AddNotificationRule](mfiles:MFiles.IRPCNotificationRules.AddNotificationRule),
//    [ModifyNotificationRule](mfiles:MFiles.IRPCNotificationRules.ModifyNotificationRule) and
//    [RemoveNotificationRule](mfiles:MFiles.IRPCNotificationRules.RemoveNotificationRule) to change
//    them. Rules are identified by `id`.
//
// To follow a single object, use
// [FollowObject](mfiles:MFiles.IRPCObjectOperations.FollowObject) instead of building the rule
// yourself. Rights are listed in [VaultAccess](mfiles:MFiles.VaultAccess); filters use the search
// conditions described in
// [Search](https://developer.m-files.com/APIs/gRPC-API/concepts/search/).
//
// **Filter-based rules.** A rule whose only subscription is `EVENT_TYPE_OBJECT_NOTIFICATION`
// notifies about the objects that match its filter, for example as a reminder, instead of about
// events. Only such rules use `options.recurring` and `notification_days_of_week`. The server keeps
// these two fields only if the session was opened with
// `ClientData.capabilities.recurring_notifications` set; otherwise it saves `recurring` as false and
// `notification_days_of_week` as every day (127).
service IRPCNotificationRules {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Notification rules" };

	// Deletes a notification rule.
	//
	// - Callers can delete their own private rules (no special right needed) and, with the vault
	//   right `manage_common_notification_rules`, common rules.
	// - Any other ID, including a private rule of another user, fails with "Not found.".
	rpc RemoveNotificationRule( RemoveNotificationRuleRequest ) returns ( RemoveNotificationRuleResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Creates a notification rule and returns its ID.
	//
	// - A private rule (`is_common` false) requires the vault right
	//   `manage_private_notification_rules` and belongs to the caller. A common rule requires
	//   `manage_common_notification_rules`. Otherwise the call fails with "Access denied.".
	// - `name` must not be empty ("The parameter is incorrect."). `id` is ignored: the server assigns
	//   a new ID. Names need not be unique, so a retried call creates a second rule.
	// - `recipients` must be a plain access control list of users and groups; pseudo-users such as
	//   "current user" are rejected.
	// - See the service overview for `recurring` and `notification_days_of_week`.
	rpc AddNotificationRule( AddNotificationRuleRequest ) returns ( AddNotificationRuleResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Replaces a notification rule, identified by its `id`, with the given definition.
	//
	// - Send the complete rule: read it with
	//   [GetNotificationRules](mfiles:MFiles.IRPCNotificationRules.GetNotificationRules), change it
	//   and send it back. The subscriptions are replaced as a whole.
	// - Saving a private rule (`is_common` false) requires `manage_private_notification_rules`;
	//   saving a common rule requires `manage_common_notification_rules`.
	// - An unknown `id` fails with "Not found.". The same validation as in
	//   [AddNotificationRule](mfiles:MFiles.IRPCNotificationRules.AddNotificationRule) applies.
	rpc ModifyNotificationRule( ModifyNotificationRuleRequest ) returns ( ModifyNotificationRuleResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets the caller's private notification rules and the common rules that apply to the caller.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Common rules are returned when the caller is among their `recipients`, or when the caller has
	//   the vault right `see_all_objects`. Private rules of other users are never returned.
	// - The order of the rules is not specified.
	rpc GetNotificationRules( GetNotificationRulesRequest ) returns ( GetNotificationRulesResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of RemoveNotificationRule.
message RemoveNotificationRuleRequest {

	// The ID of the rule to delete.
	int32 id = 1;
}

// The response of RemoveNotificationRule.
message RemoveNotificationRuleResponse {
}

// The request of AddNotificationRule.
message AddNotificationRuleRequest {

	// The rule to create. Set `name`, `subscriptions` and usually `object_filter` and `options.is_enabled`; for a common rule also `is_common` and `recipients`. `id` is ignored.
	NotificationRule utf8szrule = 1;
}

// The response of AddNotificationRule.
message AddNotificationRuleResponse {

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

// The request of ModifyNotificationRule.
message ModifyNotificationRuleRequest {

	// The complete new definition of the rule. `id` identifies the rule to change.
	NotificationRule utf8szrule = 1;
}

// The response of ModifyNotificationRule.
message ModifyNotificationRuleResponse {
}

// The request of GetNotificationRules.
message GetNotificationRulesRequest {
}

// The response of GetNotificationRules.
message GetNotificationRulesResponse {

	// The rules. Built-in common rules, such as "Assigned to me", have small fixed IDs.
	repeated NotificationRule rules = 1;
}