named_location.proto

syntax = "proto3";

package hiber.organization.location;

import "base.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.organization.location";
option java_outer_classname = "NamedLocationApi";
option go_package = ".;hiber";

/* Manage named locations for your organization.
 * This allows you to save locations to be displayed on the map or used in alarms.
 * Note that when a named location is used in an alarm, it may be exposed to child organization when the alarm
 * is available to child organizations.
 */
service NamedLocationService {
    rpc List (ListNamedLocations.Request) returns (ListNamedLocations.Response);
    rpc Create (CreateNamedLocations.Request) returns (CreateNamedLocations.Response);
    rpc Update (UpdateNamedLocation.Request) returns (UpdateNamedLocation.Response);
    rpc Delete (DeleteNamedLocation.Request) returns (DeleteNamedLocation.Response);
}

/* A named location within an organization. */
message NamedLocation {
    /* Names of locations are guaranteed to be unique per organization.
     * This means that the name can be used as a unique identifier for CRUD operations.
     */
    string name = 1;
    oneof definition {
        Location location = 2;
        Area area = 3;
        Shape shape = 4;
    }

    /* When the alarm was created. */
    Timestamp created_at = 5;

    /* When the alarm was updated. */
    Timestamp updated_at = 6;

    /* Alarms that have one or more location checks that reference this named location. */
    repeated AlarmReference referenced_by_alarms = 7;

    /* Alarm check that uses the named location. */
    message AlarmReference {
        string alarm_identifier = 1;
        string description = 2;
        string check = 3;
    }
}

/* Look up named locations by name, or by overlap with a given selection. */
message NamedLocationSelection {
    /* Free text search in the named location names. */
    optional string search = 1;

    /* Select the named locations with the given names. */
    repeated string names = 2;

    /* Select all named locations that overlap with the given LocationOverlapSelection. */
    optional LocationOverlapSelection overlaps = 3;

    /* Select named locations that are used by any of the given alarm identifiers. */
    repeated string referenced_by_alarms = 4;
}

/* Selection for overlapping with (saved) locations.
 *
 * For example:
 * - Select everything that overlaps with named location "my-area":
 *     { overlaps = { saved = "my-area" } }
 * - Select everything that overlaps with a custom shape:
 *     { overlaps = { shape = { path = ... } } }
 * - Select everything that overlaps with the intersection of a named location and a custom area:
 *     { overlaps_all = [{ saved = "my-saved-location" }, { area = ... }] }
 * - Recursive selection using a combination of any and all by adding deeper selections:
 *     { overlaps_any = [{ overlap_all = { ... } }, { saved = { .. } }] }
 */
message LocationOverlapSelection {
    oneof element {
        /* Matches anything that contains this location. */
        Location location = 1;

        /* Matching anything that overlaps with this shape. */
        Area area = 2;

        /* Matching anything that overlaps with this area. */
        Shape shape = 3;

        /* Matches anything that overlaps with this named location. */
        string name = 4;
    }

    /* Must overlap with all items.
     * If used in combination with element or overlaps_any, they must all match.
     */
    repeated LocationOverlapSelection overlaps_all = 6;

    /* Must overlap with at least one of the items.
     * If used in combination with element or overlaps_all, they must all match.
     */
    repeated LocationOverlapSelection overlaps_any = 7;
}

message ListNamedLocations {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;
        optional NamedLocationSelection selection = 2;
        optional Pagination pagination = 3;
    }

    message Response {
        repeated NamedLocation named_locations = 1;
        Pagination.Result pagination = 2;
        Request request = 3;
    }
}

message CreateNamedLocations {
    message CreateNamedLocation {
        string name = 1;
        oneof definition {
            Location location = 2;
            Area area = 3;
            Shape shape = 4;
        }
    }

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

        /* The locations to save. If the name for any of the given locations already exists, the request fails. */
        repeated CreateNamedLocation create = 3;

        repeated NamedLocation deprecated_create = 2 [deprecated = true];
    }

    message Response {
        repeated NamedLocation added = 1;
    }
}

/* Update for a named location. */
message UpdateNamedLocation {
    /* If not empty, replaces the name of the location. */
    string update_name = 1;

    /* Replace the definition for the named location. */
    oneof replace_definition {
        Location location = 2;
        Area area = 3;
        Shape shape = 4;
    }

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

        /* The name of the named location to update. */
        string name = 2;

        /* The update for the named location. */
        UpdateNamedLocation updated = 4;
    }

    message Response {
        NamedLocation updated = 1;
    }
}

/* Delete a named location.
 * Note that a named location that is referenced by one or more alarm location checks cannot be deleted without
 * deleting those alarm checks first. See the AlarmService for more information.
 */
message DeleteNamedLocation {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* The name of the named location to delete. */
        string name = 2;
    }

    message Response {
    }
}