diff --git a/CHANGELOG.md b/CHANGELOG.md index 5102a08..1c6f040 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,38 @@ # Changelog Hiber API +### 0.90 (2021-10-11) + +This release contains a number of bugfixes and removes some deprecated options from ModemAlarm. + +#### Changes + +- Fixed a few performance issues. + +##### ModemService + +- Fixed a bug where `ModemSelection.filter_by_tags` would return only the modems matching the entire set of given tags + (ALL) instead of modems with one of the given tags (ANY). + +##### ModemAlarmService + +- Remove the deprecated options on `LocationCheck`: + - Custom `area` or `shape` are no longer supported, use a named location instead. + +##### NamedLocationService + +- Cleaned up the comments which referred to saved location instead of named location. +- Added `NamedLocation.created_at`: the time it was created. +- Added `NamedLocation.updated_at`: the last time the location was updated, if any. +- Added `NamedLocation.referenced_by_alarms`, the list of alarms that reference this named location. +- Using `NamedLocation` for create and updated is no longer practical now that we have added more fields: + - Introduced `CreateNamedLocation` to be used to in `CreateNamedLocations.Request`. + - Introduced `UpdateNamedLocation` fields to be used to in `UpdateNamedLocation.Request`. +- Fixed a bug where a named location that is used in an alarm check could still be deleted. + +##### SimulationService + +- Fixed a bug where, in rare cases, simulated messages might end up with a sent time outside the configured delay range. + ### 0.88 (2021-09-09) This release contains a number of bug fixes and usability improvements. diff --git a/docs/modem_alarm.md b/docs/modem_alarm.md index 7acb22f..e2bce66 100644 --- a/docs/modem_alarm.md +++ b/docs/modem_alarm.md @@ -595,16 +595,12 @@ Has the following parameters: Check that the device location is within a given area. Has the following parameters: -- location.expected: replace the expected area or shape -- location.area: replace the expected area -- location.shape: replace the expected shape +- location.expected: replace the referenced named location - location.named: replace the referenced named location | Field | Type | Description | | ----- | ---- | ----------- | -| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expected**.area | [ hiber.Area](#hiberarea) | none | -| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expected**.shape | [ hiber.Shape](#hibershape) | none | -| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expected**.named | [ string](#string) | Specify the name of a name location (NamedLocation) that the device must be in. | +| named | [ string](#string) | Specify the name of a named location (NamedLocation) that the device must be in. | ### ModemAlarm.HealthLevelAfterResolved diff --git a/docs/named_location.md b/docs/named_location.md index 59132bc..85347de 100644 --- a/docs/named_location.md +++ b/docs/named_location.md @@ -11,6 +11,7 @@ - Messages - [CreateNamedLocations](#createnamedlocations) + - [CreateNamedLocations.CreateNamedLocation](#createnamedlocationscreatenamedlocation) - [CreateNamedLocations.Request](#createnamedlocationsrequest) - [CreateNamedLocations.Response](#createnamedlocationsresponse) - [DeleteNamedLocation](#deletenamedlocation) @@ -21,6 +22,7 @@ - [ListNamedLocations.Response](#listnamedlocationsresponse) - [LocationOverlapSelection](#locationoverlapselection) - [NamedLocation](#namedlocation) + - [NamedLocation.AlarmReference](#namedlocationalarmreference) - [NamedLocationSelection](#namedlocationselection) - [UpdateNamedLocation](#updatenamedlocation) - [UpdateNamedLocation.Request](#updatenamedlocationrequest) @@ -73,9 +75,9 @@ ## NamedLocationService -Manage saved locations for your organization. +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 saved location is used in an alarm, it may be exposed to child organization when the alarm +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. ### List @@ -110,6 +112,17 @@ is available to child organizations. +### CreateNamedLocations.CreateNamedLocation + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| name | [ string](#string) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.location | [ hiber.Location](#hiberlocation) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.area | [ hiber.Area](#hiberarea) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.shape | [ hiber.Shape](#hibershape) | none | + ### CreateNamedLocations.Request @@ -117,7 +130,8 @@ is available to child organizations. | Field | Type | Description | | ----- | ---- | ----------- | | organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| create | [repeated NamedLocation](#namedlocation) | The locations to save. If the name for any of the given locations already exists, the request fails. | +| create | [repeated CreateNamedLocations.CreateNamedLocation](#createnamedlocationscreatenamedlocation) | The locations to save. If the name for any of the given locations already exists, the request fails. | +| deprecated_create | [repeated NamedLocation](#namedlocation) | none | ### CreateNamedLocations.Response @@ -129,7 +143,9 @@ is available to child organizations. ### DeleteNamedLocation - +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. ### DeleteNamedLocation.Request @@ -139,7 +155,7 @@ is available to child organizations. | Field | Type | Description | | ----- | ---- | ----------- | | organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| name | [ string](#string) | The name of the saved location to delete. | +| name | [ string](#string) | The name of the named location to delete. | ### DeleteNamedLocation.Response @@ -176,11 +192,11 @@ is available to child organizations. Selection for overlapping with (saved) locations. For example: -- Select everything that overlaps with saved location "my-area": +- 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 saved location and a custom area: +- 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 = { .. } }] } @@ -196,7 +212,7 @@ For example: ### NamedLocation -A saved location within an organization. +A named location within an organization. | Field | Type | Description | | ----- | ---- | ----------- | @@ -204,21 +220,41 @@ A saved location within an organization. | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.location | [ hiber.Location](#hiberlocation) | none | | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.area | [ hiber.Area](#hiberarea) | none | | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.shape | [ hiber.Shape](#hibershape) | none | +| created_at | [ hiber.Timestamp](#hibertimestamp) | When the alarm was created. | +| updated_at | [ hiber.Timestamp](#hibertimestamp) | When the alarm was updated. | +| referenced_by_alarms | [repeated NamedLocation.AlarmReference](#namedlocationalarmreference) | Alarms that have one or more location checks that reference this named location. | + +### NamedLocation.AlarmReference + +Alarm check that uses the named location. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| alarm_identifier | [ string](#string) | none | +| description | [ string](#string) | none | +| check | [ string](#string) | none | ### NamedLocationSelection -Look up saved locations by name, or by overlap with a given selection. +Look up named locations by name, or by overlap with a given selection. | Field | Type | Description | | ----- | ---- | ----------- | -| search | [ string](#string) | Free text search in the saved location names. | -| names | [repeated string](#string) | Select the saved locations with the given names. | -| overlaps | [ LocationOverlapSelection](#locationoverlapselection) | Select all saved locations that overlap with the given LocationOverlapSelection. | +| search | [ string](#string) | Free text search in the named location names. | +| names | [repeated string](#string) | Select the named locations with the given names. | +| overlaps | [ LocationOverlapSelection](#locationoverlapselection) | Select all named locations that overlap with the given LocationOverlapSelection. | +| referenced_by_alarms | [repeated string](#string) | Select named locations that are used by any of the given alarm identifiers. | ### UpdateNamedLocation +Update for a named location. - +| Field | Type | Description | +| ----- | ---- | ----------- | +| update_name | [ string](#string) | If not empty, replaces the name of the location. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **replace_definition**.location | [ hiber.Location](#hiberlocation) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **replace_definition**.area | [ hiber.Area](#hiberarea) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **replace_definition**.shape | [ hiber.Shape](#hibershape) | none | ### UpdateNamedLocation.Request @@ -227,8 +263,9 @@ Look up saved locations by name, or by overlap with a given selection. | Field | Type | Description | | ----- | ---- | ----------- | | organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| name | [ string](#string) | The name of the saved location to update. | -| updated | [ NamedLocation](#namedlocation) | The new saved location. If the name is different, the saved location is renamed. | +| name | [ string](#string) | The name of the named location to update. | +| updated | [ UpdateNamedLocation](#updatenamedlocation) | The update for the named location. | +| deprecated_updated | [ NamedLocation](#namedlocation) | none | ### UpdateNamedLocation.Response diff --git a/modem_alarm.proto b/modem_alarm.proto index 5f0a4fb..0335c34 100644 --- a/modem_alarm.proto +++ b/modem_alarm.proto @@ -209,20 +209,14 @@ message ModemAlarm { /* Check that the device location is within a given area. * * Has the following parameters: - * - location.expected: replace the expected area or shape - * - location.area: replace the expected area - * - location.shape: replace the expected shape + * - location.expected: replace the referenced named location * - location.named: replace the referenced named location */ message LocationCheck { - /* The location the device must be in. */ - oneof expected { - Area area = 1; - Shape shape = 2; + /* Specify the name of a named location (NamedLocation) that the device must be in. */ + string named = 3; - /* Specify the name of a name location (NamedLocation) that the device must be in. */ - string named = 3; - } + reserved 1, 2; } /* Check whether the device exceeds inactivity limits. diff --git a/named_location.proto b/named_location.proto index 7c738db..4545f6e 100644 --- a/named_location.proto +++ b/named_location.proto @@ -9,9 +9,9 @@ option java_package = "global.hiber.api.grpc.organization.location"; option java_outer_classname = "NamedLocationApi"; option go_package = "hiber"; -/* Manage saved locations for your organization. +/* 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 saved location is used in an alarm, it may be exposed to child organization when the alarm + * 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 { @@ -21,7 +21,7 @@ service NamedLocationService { rpc Delete (DeleteNamedLocation.Request) returns (DeleteNamedLocation.Response); } -/* A saved location within an organization. */ +/* A named location within an organization. */ message NamedLocation { string name = 1; oneof definition { @@ -29,28 +29,47 @@ message NamedLocation { 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 saved locations by name, or by overlap with a given selection. */ +/* Look up named locations by name, or by overlap with a given selection. */ message NamedLocationSelection { - /* Free text search in the saved location names. */ + /* Free text search in the named location names. */ string search = 1; - /* Select the saved locations with the given names. */ + /* Select the named locations with the given names. */ repeated string names = 2; - /* Select all saved locations that overlap with the given LocationOverlapSelection. */ + /* Select all named locations that overlap with the given LocationOverlapSelection. */ 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 saved location "my-area": + * - 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 saved location and a custom area: + * - 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 = { .. } }] } @@ -97,12 +116,23 @@ message ListNamedLocations { } 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. */ string organization = 1; /* The locations to save. If the name for any of the given locations already exists, the request fails. */ - repeated NamedLocation create = 2; + repeated CreateNamedLocation create = 3; + + repeated NamedLocation deprecated_create = 2 [deprecated = true]; } message Response { @@ -110,16 +140,29 @@ message CreateNamedLocations { } } +/* 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. */ string organization = 1; - /* The name of the saved location to update. */ + /* The name of the named location to update. */ string name = 2; - /* The new saved location. If the name is different, the saved location is renamed. */ - NamedLocation updated = 3; + /* The update for the named location. */ + UpdateNamedLocation updated = 4; + + NamedLocation deprecated_updated = 3 [deprecated = true]; } message Response { @@ -127,12 +170,16 @@ message UpdateNamedLocation { } } +/* 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. */ string organization = 1; - /* The name of the saved location to delete. */ + /* The name of the named location to delete. */ string name = 2; }