assignment.proto

syntax = "proto3";

package hiber.assign;

import "google/protobuf/struct.proto";

import "base.proto";
import "asset.proto";
import "modem.proto";
import "modem_alarm.proto";
import "modem_message_body_parser.proto";
import "tag.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.assign";
option java_outer_classname = "AssignmentApi";
option go_package = ".;hiber";

service AssignmentService {
    /* List assignments. */
    rpc List (ListAssignments.Request) returns (ListAssignments.Response);

    /* Assign something, like an alarm to a modem. */
    rpc Assign (Assign.Request) returns (Assign.Response);

    /* End an assignment, like an alarm to a modem. */
    rpc Unassign (Unassign.Request) returns (Unassign.Response);

    /* Delete an assignment, even if it has a time range. */
    rpc Delete (DeleteAssignment.Request) returns (DeleteAssignment.Response);

    /* List assets with the devices and tags they are assigned to. */
    rpc AssetAssignments (ListAssetAssignments.Request) returns (ListAssetAssignments.Response);

    /* List modems with tags, alarms and parsers assigned to them. */
    rpc ModemAssignments (ListModemAssignments.Request) returns (ListModemAssignments.Response);

    /* List tags with the modems, alarms and parsers they are assigned to. */
    rpc TagAssignments (ListTagAssignments.Request) returns (ListTagAssignments.Response);

    /* List alarms with the modems and parsers they are assigned to. */
    rpc AlarmAssignments (ListAlarmAssignments.Request) returns (ListAlarmAssignments.Response);

    /* List alarms with the modems and parsers they are assigned to. */
    rpc ModemMessageBodyParserAssignments (ListModemMessageBodyParserAssignments.Request) returns (ListModemMessageBodyParserAssignments.Response);
}

/* The types of assignment available, like assigning a message body parser to a modem. */
enum AssignmentType {
    DEFAULT = 0;

    /* Assignment that assigns a message body parser to a modem. */
    ASSIGNS_MESSAGE_BODY_PARSER_TO_MODEM = 1;

    /* Assignment that assigns a modem alarm to a modem. */
    ASSIGNS_ALARM_TO_MODEM = 2;

    /* Assignment that assigns an alarm to an asset. */
    ASSIGNS_ALARM_TO_ASSET = 9;

    /* Assignment that assigns a modem to a tag. */
    ASSIGNS_MODEM_TO_TAG = 4;

    /* Assignment that assigns a message body parser to a tag, effectively assigning it to all modems with that tag. */
    ASSIGNS_MESSAGE_BODY_PARSER_TO_TAG = 5;

    /* Assignment that assigns a modem alarm to a tag, effectively assigning it to all modems with that tag. */
    ASSIGNS_ALARM_TO_TAG = 6;

    /* Assignment that assigns an asset to a tag. */
    ASSIGNS_ASSET_TO_TAG = 7;

    /* Assignment that assigns an asset to a device. */
    ASSIGNS_ASSET_TO_DEVICE = 8;

    reserved 3;
}

/* An assignment assigning one thing to another.
 *
 * Assignment is transitive: when an alarm or parser is assigned to a tag, and the tag is assigned to a modem,
 *   the alarm or parser is considered assigned to that modem.
 * This only works in one direction, though. Assigning the alarm or parser to the modem directly does not also assign
 * the tag.
 *
 * Assignment can have a custom start and end time.
 * This can extend into the past, but would not have effect in the past for assignments like parsers.
 * It would however work for assets having access to device data.
 * This can also extend into the future, but while the unassigned event will be produced, the assignment will
 * still be visible until the given time.
 *
 * Assignments that are no longer active (end time is in the past) and that no longer have an effect
 * (currently only asset device assignment has an ongoing effect) may be cleaned up automatically.
 */
message Assignment {
    message AlarmAssignment {
        string identifier = 1;
        string name = 5;
        string description = 2;
        google.protobuf.Struct parameters = 3;

        reserved 4;
    }

    message ModemMessageBodyParserAssignment {
        string identifier = 1;
        string name = 2;
        string owner_organization = 3;
    }

    /* The type of assignment. This is a helper enum to indicate which fields are set. */
    AssignmentType type = 1;

    /* Time this assignment started. This is always in the past. */
    Timestamp start = 9;

    /* Time this assignment ended, if it has ended.
     * Inactive assignments that no longer have an effect may be cleaned up automatically.
     */
    optional Timestamp end = 10;

    oneof assign {
        ModemMessageBodyParserAssignment assign_parser = 3;
        AlarmAssignment assign_alarm = 5;
        string assign_modem = 6;
        string assign_asset = 8;
    }

    oneof to {
        string to_modem = 2;
        ModemMessageBodyParserAssignment to_parser = 4;
        tag.Tag to_tag = 7;
        string to_asset = 11;
    }
}

message AssignmentSelection {
    message AssignmentTypes {
        repeated AssignmentType include = 1;
        repeated AssignmentType exclude = 2;
    }

    /* Select the assets to return the assignments for. Optional, when omitted or empty everything is included. */
    optional asset.AssetSelection assets = 6;

    /* Select the modems to return the assignments for. Optional, when omitted or empty everything is included. */
    optional modem.ModemSelection modems = 1;

    /* Select the alarms to return the assignments for. Optional, when omitted or empty everything is included. */
    optional modem.alarm.ModemAlarmSelection modem_alarms = 2;

    /* Select the message body parsers to return the assignments for.
     * Optional, when omitted or empty everything is included.
     */
    optional modem.message.bodyparser.ModemMessageBodyParserSelection modem_message_body_parsers = 3;

    /* Select the tags to return the assignments for. Optional, when omitted or empty everything is included. */
    optional tag.TagSelection tags = 5;

    /* Select by type of assignment. */
    optional AssignmentTypes types = 4;
}

message ListAssignments {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the assignments to list. Optional, when omitted or empty everything is included. */
        optional AssignmentSelection selection = 2;
        optional Pagination pagination = 3;

        /* Include assignments that are no longer active. */
        optional bool include_inactive_assignments = 4;
    }

    message Response {
        /* The assignments as identifiers in the selection. */
        repeated Assignment assignments = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}

/* Add assignments. */
message Assign {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        oneof assign {
            modem.message.bodyparser.ModemMessageBodyParserSelection assign_parsers = 2;
            modem.alarm.ModemAlarmSelection assign_alarms = 4;
            modem.ModemSelection assign_modems = 7;
            asset.AssetSelection assign_assets = 9;
        }

        oneof to {
            modem.ModemSelection to_modems = 5;
            tag.TagSelection to_tags = 8;
            asset.AssetSelection to_assets = 12;
        }

        /* The alarm parameters, by alarm identifier, if any, overriding any default values in the alarm(s). */
        map<string, google.protobuf.Struct> alarm_parameters = 6;

        /* Time that the assignment should be active.
         * This sets the assignment to start in the past, but would not have effect in the past for assignments like
         * parsers and alarms (they will only be triggered for new messages / values).
         * It would however work for assets having access to device data.
         * This is not allowed to be a value in the future at the moment.
         */
        optional Timestamp override_time = 10;

        /* Time that the assignment ended.
         * This marks the assignment as ended at the given moment in the past, but would not have effect in the past
         * for assignments like parsers and alarms (i.e. no alarm events are removed).
         * It would however work for assets having access to device data.
         * This is not allowed to be a value in the future at the moment.
         */
        optional Timestamp end_time = 11;

        /* Instead of throwing an error when there are conflicting assignments,
         * unassign the conflicting assignments with the given time (override_time or now) and
         * then making the assignment.
         */
        optional bool override_conflicting_assignments = 13;

        /* When overriding assignments, we may run into a case where a previous assignment would be completely replaced.
         * Since this is questionable, doing so required an additional opt-in with this flag.
         */
        optional bool override_conflicting_assignments_allow_delete = 14;

        reserved 3;
    }
    message Response {
        repeated Assignment assigned = 1;
        Request request = 2;
    }
}

/* Remove a assignment. */
message Unassign {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        oneof unassign {
            modem.message.bodyparser.ModemMessageBodyParserSelection unassign_parsers = 2;
            modem.alarm.ModemAlarmSelection unassign_alarms = 4;
            modem.ModemSelection unassign_modems = 6;
            asset.AssetSelection unassign_assets = 9;
        }

        oneof from {
            modem.ModemSelection from_modems = 5;
            tag.TagSelection from_tags = 7;
            asset.AssetSelection from_assets = 11;
        }

        oneof time {
            /* Time that the assignment ended.
             * This marks the assignment as ended at the given moment in the past, but would not have effect in the past
             * for assignments like parsers and alarms (i.e. no alarm events are removed).
             * It would however work for assets having access to device data.
             * This is not allowed to be a value in the future at the moment.
             */
            Timestamp override_time = 10;

            /* Remove time from the assignment, if any.
             * Effectively deletes the assignment if it was set with a time.
             * Setting this to true makes this identical to using the Delete rpc.
             */
            bool remove_time = 12;
        }

        reserved 3;
    }
    message Response {
        repeated Assignment unassigned = 1;
        Request request = 2;
    }
}

message DeleteAssignment {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        oneof unassign {
            modem.message.bodyparser.ModemMessageBodyParserSelection unassign_parsers = 2;
            modem.alarm.ModemAlarmSelection unassign_alarms = 4;
            modem.ModemSelection unassign_modems = 6;
            asset.AssetSelection unassign_assets = 9;
        }

        oneof from {
            modem.ModemSelection from_modems = 5;
            tag.TagSelection from_tags = 7;
            asset.AssetSelection from_assets = 11;
        }

        reserved 3;
    }
    message Response {
        repeated Assignment deleted = 1;
        Request request = 2;
    }
}

message ListAssetAssignments {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the assignments to list. Optional, when omitted or empty everything is included. */
        optional AssignmentSelection selection = 2;
        optional Pagination pagination = 3;

        /* Whether to include assets that are in the selection and have no assignments. */
        optional bool include_assets_without_assignments = 4;

        /* Whether to include the full alarms that are assigned, instead of just assignment. */
        optional bool include_alarm_details = 5;

        /* Apply your UnitPreferences to the alarm checks.
         * For example, if a temperature check is configured in kelvin, but your unit preferences specify celsius for
         * temperature, the check value will be converted to celsius instead.
         */
        optional bool apply_unit_preferences = 6;
    }

    message Response {
        /* Things that an alarm is assigned to. */
        message AssetAssignment {
            string organization = 1;
            string asset_identifier = 2;

            /* The devices assigned to this asset. */
            repeated string devices = 3;

            /* The tags for this asset. */
            repeated tag.Tag tags = 4;

            /* The identifiers and parameters of the alarms that are assigned to this asset. */
            repeated Assignment.AlarmAssignment alarms = 5;

            /* The alarms that are assigned to this asset, if you have permission to view them. */
            repeated modem.alarm.ModemAlarm alarm_details = 6;
        }

        repeated AssetAssignment assets = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}

message ListModemAssignments {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the assignments to list. Optional, when omitted or empty everything is included. */
        optional AssignmentSelection selection = 2;
        optional Pagination pagination = 3;

        /* Whether to include the full alarms that are assigned, instead of just assignment. */
        optional bool include_alarm_details = 4;

        /* Whether to include the full parsers that are assigned, instead of just assignment. */
        optional bool include_message_body_parser_details = 5;

        /* Whether to include, for example, the message body parser ksy content in the result.
         * Excluded by default to save data.
         */
        optional bool include_message_body_parser_content = 6;

        /* Whether to include modems that are in the selection and have no assignments. */
        optional bool include_modems_without_assignments = 8;

        /* Apply your UnitPreferences to the alarm checks.
         * For example, if a temperature check is configured in kelvin, but your unit preferences specify celsius for
         * temperature, the check value will be converted to celsius instead.
         */
        optional bool apply_unit_preferences = 9;

        reserved 7;
    }

    message Response {
        /* Things that are assigned to a modem. */
        message ModemAssignment {
            string organization = 1;
            string modem_number = 2;

            /* The identifiers of the message body parsers that are assigned to this modem. */
            repeated Assignment.ModemMessageBodyParserAssignment message_body_parsers = 4;

            /* The identifiers and parameters of the alarms that are assigned to this modem. */
            repeated Assignment.AlarmAssignment alarms = 5;

            /* The tags for this modem. */
            repeated tag.Tag tags = 8;

            /* The details of the parsers assigned to this modem. */
            repeated modem.message.bodyparser.ModemMessageBodyParser message_body_parser_details = 6;

            /* The alarms that are assigned to this modem, if you have permission to view them. */
            repeated modem.alarm.ModemAlarm alarm_details = 7;

            /* The assets assigned to this device. */
            repeated string asset_identifiers = 9;

            reserved 3;
        }

        repeated ModemAssignment modems = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}

message ListTagAssignments {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the assignments to list. Optional, when omitted or empty everything is included. */
        optional AssignmentSelection selection = 2;
        optional Pagination pagination = 3;

        /* Whether to include the full alarms that are assigned, instead of just assignment. */
        optional bool include_alarm_details = 4;

        /* Whether to include the full parsers that are assigned, instead of just assignment. */
        optional bool include_message_body_parser_details = 5;

        /* Whether to include, for example, the message body parser ksy content in the result.
         * Excluded by default to save data.
         */
        optional bool include_message_body_parser_content = 6;

        /* Whether to include alarms that are in the selection and have no assignments. */
        optional bool include_tags_without_assignments = 8;

        /* Apply your UnitPreferences to the alarm checks.
         * For example, if a temperature check is configured in kelvin, but your unit preferences specify celsius for
         * temperature, the check value will be converted to celsius instead.
         */
        optional bool apply_unit_preferences = 9;

        reserved 7;
    }

    message Response {
        /* Things that an alarm is assigned to. */
        message TagAssignment {
            string organization = 1;
            tag.Tag tag = 2;

            /* The modems with this tag. */
            repeated string modems = 3;

            /* The identifiers of the message body parsers that are assigned to this tag. */
            repeated Assignment.ModemMessageBodyParserAssignment message_body_parsers = 4;

            /* The identifiers and parameters of the alarms that are assigned to this tag. */
            repeated Assignment.AlarmAssignment alarms = 5;

            /* The details of the parsers assigned to this tag. */
            repeated modem.message.bodyparser.ModemMessageBodyParser message_body_parser_details = 6;

            /* The alarms that are assigned to this tag, if you have permission to view them. */
            repeated modem.alarm.ModemAlarm alarm_details = 7;

            /* The assets assigned to this tag. */
            repeated string asset_identifiers = 8;
        }

        repeated TagAssignment tags = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}

message ListAlarmAssignments {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the assignments to list. Optional, when omitted or empty everything is included. */
        optional AssignmentSelection selection = 2;
        optional Pagination pagination = 3;

        /* Whether to include modems from child organizations in this list (and which organizations). */
        optional Filter.ChildOrganizations include_child_organizations = 4;

        /* Whether to include alarms that are in the selection and have no assignments. */
        optional bool include_alarms_without_assignments = 5;

        /* Apply your UnitPreferences to the alarm checks.
         * For example, if a temperature check is configured in kelvin, but your unit preferences specify celsius for
         * temperature, the check value will be converted to celsius instead.
         */
        optional bool apply_unit_preferences = 6;
    }

    message Response {
        /* Things that an alarm is assigned to. */
        message AlarmAssignment {
            message ToModem {
                string modem_number = 1;
                google.protobuf.Struct parameters = 2;
            }
            message ToTag {
                tag.Tag tag = 1;
                google.protobuf.Struct parameters = 2;
            }
            message ToAsset {
                string asset_identifier = 1;
                google.protobuf.Struct parameters = 2;
            }

            string organization = 1;
            modem.alarm.ModemAlarm alarm = 2;

            /* The modem numbers this alarm is assigned to, with the alarm parameters. */
            repeated ToModem modems = 3;

            /* The tags this alarm is assigned to, with the alarm parameters. */
            repeated ToTag tags = 4;

            /* The assets this alarm is assigned to, with the alarm parameters. */
            repeated ToAsset assets = 5;
        }

        repeated AlarmAssignment alarms = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}

message ListModemMessageBodyParserAssignments {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the assignments to list. Optional, when omitted or empty everything is included. */
        optional AssignmentSelection selection = 2;
        optional Pagination pagination = 3;

        /* Whether to include modems from child organizations in this list (and which organizations). */
        optional Filter.ChildOrganizations include_child_organizations = 4;

        /* Whether to include alarms that are in the selection and have no assignments. */
        optional bool include_parser_without_assignments = 5;
    }

    message Response {
        /* Things that an alarm is assigned to. */
        message ModemMessageBodyParserAssignment {
            string organization = 1;
            modem.message.bodyparser.ModemMessageBodyParser message_body_parser = 2;

            /* The modem numbers this alarm is assigned to, with the alarm parameters. */
            repeated string modems = 3;

            /* The tags this alarm is assigned to, with the alarm parameters. */
            repeated tag.Tag tags = 4;
        }

        repeated ModemMessageBodyParserAssignment parsers = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}