From 400c61c6d23f5f117816c89bf0e36eb43f96af97 Mon Sep 17 00:00:00 2001 From: Wouter Bouvy Date: Mon, 29 Jun 2020 14:46:26 +0200 Subject: [PATCH] 0.51 --- CHANGELOG.md | 125 ++++++- base.proto | 22 +- dashboard.proto | 18 +- event-json-examples/README.md | 5 + .../modem-message-body-parsed.json | 29 ++ .../modem-message-body-received.json | 28 ++ .../modem-message-received.json | 49 +++ event.proto | 273 ++++++++++++--- modem.proto | 46 ++- modem_message_body_parser.proto | 316 ++++++++++++------ modem_message_body_parser_assignment.proto | 122 +++++++ ...age_body_parser_automatic_assignment.proto | 274 +++++++++++++++ token.proto | 1 + 13 files changed, 1143 insertions(+), 165 deletions(-) create mode 100644 event-json-examples/README.md create mode 100644 event-json-examples/modem-message-body-parsed.json create mode 100644 event-json-examples/modem-message-body-received.json create mode 100644 event-json-examples/modem-message-received.json create mode 100644 modem_message_body_parser_assignment.proto create mode 100644 modem_message_body_parser_automatic_assignment.proto diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d6bb8c..3f8be3d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,128 @@ # Changelog Hiber API +### 0.51 (2020-06-29) + +This release introduces automatic assignment rules for modem message body parsers. +These rules can be used to assign body parsers to modems across organizations, based on criteria like +tags, manufacturers and peripherals. + +#### Changes + +##### DashboardService + +- Fixed a few comments. + +##### EventService + +- Added two new modem message events: + - `ModemMessageBodyReceivedEvent` is a simplified version of the `ModemMessageReceivedEvent` that + doesn't have a `Message` object. Instead, it only has `message_id`, `sent_at` and `body`. + This is useful for the cases where you need a lighter format and are not using body parsing. + - `ModemMessageBodyParsedEvent` is an event that is produced for each message, for each body parser. + If you assign 3 body parsers to modem, they all try to parse the message. Every success produces this event. + This is useful for the cases where you're only interested in the parsed body. + - For each of these events, an `EventType` has been added to `base.proto` + - For all three message events, an example json has been added under `event-json-examples`. + In the future, more examples for other event types will be placed there. + +- Added new body parser events: + - `MessageBodyParserEvent.CreatedEvent` is produced when a new body parser is created. + - `MessageBodyParserEvent.UpdatedEvent` is produced when a body parser is updated. + - `MessageBodyParserEvent.DeletedEvent` is produced when a body parser is deleted. + - `MessageBodyParserEvent.AssignedEvent` is produced when a body parser is directly assigned to a modem. + - `MessageBodyParserEvent.UnassignedEvent` is produced when a body parser is removed from to a modem. + - `MessageBodyParserEvent.AutomaticAssignmentEvent.CreatedEvent` is produced when a new automatic assignment rule + for body parsers is created. + - `MessageBodyParserEvent.AutomaticAssignmentEvent.UpdatedEvent` is produced when an automatic assignment rules for + for body parsers is updated. + - `MessageBodyParserEvent.AutomaticAssignmentEvent.DeletedEvent` is produced when an automatic assignment rules for + for body parsers is deleted. + - For each of these events, an `EventType` has been added to `base.proto` + +- Added a new event `UserValidationUpdatedEvent` when user validation has been updated. + +- Fixed a few imports and comments. + +##### ModemService + +- `ModemMessage.ParsedBody` was updated to reflect the changes to body parsers: + - Added `parser_identifier` to `ParsedBody`. This field contains a globally unique identifier + for the body parser used to parse the message body. + - The `parser_id` is now deprecated in favour of the `identifier`. + - Wrapped `result` and `error` in a `oneof`, since only one can be present. + +- Added `UpdateModemStatusRequest.modem_selection` to update the status for multiple modems at the same time. + - Deprecated the single modem field `UpdateModemStatusRequest.modem_number`, since the selection covers that case. + +- Fixed a few imports and comments. + +##### ModemMessageBodyParserService + +- Deprecated the assignment-related calls in favour of the new `ModemMessageBodyParserAssignmentService`: + - Deprecated `ListAssignedParsers` and `ListAssignedParsersRequest` + - Deprecated `AssignToModems` and `AssignModemMessageBodyParserToModemsRequest` + - Deprecated `RemoveFromModems` and `RemoveModemMessageBodyParserFromModemsRequest` + +- Updated `ModemMessageBodyParser` to match the new global body parser usage better: + - Added `identifier` to `ModemMessageBodyParser`, a globally unique identifier for the body parser. + - Added `organization` to `ModemMessageBodyParser`, to show who owns the body parsers. + - Deprecated `id` in `ModemMessageBodyParser` in favour of the `identifier`. + - **[B]** Dropped `ModemMessageBodyParser.AvailableToChildOrganizations.parser_id_for_child_organizations` + in favour of the new `identifier`. + +- Updated `ModemMessageBodyParserSelection` to match the changes to `ModemMessageBodyParser`: + - **[B]** Removed `SelectIdentifier` and its related field. + - Added `identifiers` to search on identifiers. + - Deprecated `ids` in `ModemMessageBodyParser` in favour of `identifiers`. + - Renamed `exclude_provided_parsers` to `only_owned_parsers`. + - Renamed `providers` to `owner_organizations`. + +- Added `ListModemMessageBodyParsersRequest.exclude_content` to not fill the content of the returned body parsers + (either the `content_ksy` or `simple_parser` fields). + +- Updated `UploadModemMessageBodyParserRequest`, `UpdateSimpleModemMessageBodyParserRequest`, + `RenameModemMessageBodyParserRequest` and `UpdateChildOrganizationAvailabilityRequest` to match the changes + to `ModemMessageBodyParser`: + - Added `identifier` and deprecated `id`. + +- Updated `TestModemMessageBodyParserRequest` to match the changes to `ModemMessageBodyParser`: + - **[B]** Removed the `SelectIdentifier`-based field. + - Added `identifier`. + +##### ModemMessageBodyParserAutomaticAssignmentService + +- Added `ModemMessageBodyParserAutomaticAssignmentService` to manage automatic assignment rules for body parsers. + + These rules can be used to automatically assign body parsers to modem that match specific criteria. + For example, all modems with tag "parse-this" and a peripheral "sensor": "water-sensor-brand-x" can be + assigned a parser for the data format for that peripheral. + + Criteria can be used and combined in a multitude of ways, but here are a few notable uses: + - assign a parser to tag, so assigning it to modems is as easy as adding a tag to that modem + - assign a parser to peripheral, so each modem with that peripheral gets that parser by default + - blacklisting a parser from a tag, so you can set that tag to exclude a modem from being assigned that parser + - blacklisting a parser from a set of modems, so you can exclude a set of modem from being assigned that parser + - add a parser to devices you manufacture, and apply this to child organizations, so that all of your + customers' modems are automatically assigned that parser + +##### ModemMessageBodyParserAssignmentService + +- Added `ModemMessageBodyParserAssignmentService` to assign body parsers directly to modems and + list assignments based on direct assignments to modems and the result of applying automatic assignment rules. + +##### TokenService + +- Added the `created` `Token` to `CreateTokenRequest`, so the output is more that just the token string. + +#### Backwards incompatible changes + +- **[B]** Removed `SelectIdentifier` and its related field from `ModemMessageBodyParserSelection`. + Use the new `identifier` field instead. +- **[B]** Dropped `parser_id_for_child_organizations` from `ModemMessageBodyParser.AvailableToChildOrganizations`. + Use the new `identifier` field instead. +- **[B]** Removed the `SelectIdentifier`-based field from `TestModemMessageBodyParserRequest`. + Use the new `identifiers` field instead. + ### 0.50 (2020-06-18) #### Changes @@ -258,7 +381,7 @@ This release contains a few minor api tweaks and one semi-breaking change. ##### ModemMessageBodyParserService -- Added a `Test` command to test a payload parser on a given byte sequence, or an existing message id. +- Added a `Test` command to test a body parser on a given byte sequence, or an existing message id. ##### UserService diff --git a/base.proto b/base.proto index 6349106..b44e08e 100644 --- a/base.proto +++ b/base.proto @@ -165,8 +165,7 @@ message Pagination { Pagination previous = 6; Pagination next = 7; - /** - * Indicates that the total is an approximation, and not an exact value. + /* Indicates that the total is an approximation, and not an exact value. * This can be set for data that changes often, or is generally only fetched in an infinite scrolling manner. * For example, unbundled events are likely to return an approximated total, but not guaranteed to do so. */ @@ -193,11 +192,22 @@ enum EventType { MODEM_ACTIVATED = 33; MODEM_STALE = 16; MODEM_MESSAGE_RECEIVED = 5; + MODEM_MESSAGE_PARSED = 39; + MODEM_MESSAGE_BODY_RECEIVED = 45; MODEM_MESSAGE_DROPPED = 13; MODEM_MESSAGE_DELAYED = 14; MODEM_MESSAGE_CANNOT_BE_PARSED = 15; MODEM_MESSAGE_SUMMARY = 42; + MODEM_MESSAGE_BODY_PARSER_CREATED = 46; + MODEM_MESSAGE_BODY_PARSER_UPDATED = 47; + MODEM_MESSAGE_BODY_PARSER_DELETED = 48; + MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED = 49; + MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED = 50; + MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED = 51; + MODEM_MESSAGE_BODY_PARSER_ASSIGNED = 52; + MODEM_MESSAGE_BODY_PARSER_UNASSIGNED = 53; + MODEM_TRANSFER_STARTED = 17; MODEM_TRANSFER_RECEIVED = 18; MODEM_TRANSFER_CANCELLED = 19; @@ -217,6 +227,8 @@ enum EventType { USER_ADDED = 9; USER_REMOVED = 10; + USER_VALIDATION_UPDATED = 54; + TOKEN_CREATED = 31; TOKEN_EXPIRY_WARNING = 25; TOKEN_EXPIRED = 26; @@ -243,6 +255,12 @@ message Filter { bool include_all = 1; repeated string include = 2; repeated string exclude = 3; + + /* Update object to update a Filter.ChildOrganizations field. */ + message Update { + bool updated = 1; + Filter.ChildOrganizations value = 2; + } } message Organizations { diff --git a/dashboard.proto b/dashboard.proto index 390b894..2949be4 100644 --- a/dashboard.proto +++ b/dashboard.proto @@ -23,32 +23,32 @@ service DashboardService { */ message DashboardRequest { message Response { - // list of ground stations and their location + /* List of ground stations and their location. */ repeated hiber.map.GroundStation ground_stations = 1 [deprecated=true]; - // list of map blocks and their modem count, for density map + /* List of map blocks and their modem count, for density map. */ repeated hiber.map.MapBlock map_blocks = 2 [deprecated=true]; repeated hiber.modem.MessageCountRequest.Response.MessageCount message_count_per_day = 3; - // counts of the number of modems with warning and errors + /* Counts of the number of modems with warning and errors. */ int32 modem_warning_count = 4; int32 modem_error_count = 5; reserved 6; DashboardRequest request = 7; - // returns event bundles matching the given selection, or an empty list if the event selection wasn't set + /* Returns event bundles matching the given selection, or an empty list if the event selection wasn't set. */ repeated hiber.event.BundledEvent events = 8; repeated hiber.map.Satellite satellites = 9 [deprecated=true]; } /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; - /** Selection for ground stations and map blocks. */ + /* Selection for ground stations and map blocks. */ hiber.map.MapSelection selection = 2 [deprecated=true]; - /** Selection for modem messages. */ + /* Selection for modem messages. */ hiber.modem.ModemMessageSelection message_count_selection = 3; - /** Selection for bundled events, only used when any value is set. */ + /* Selection for bundled events, only used when any value is set. */ hiber.event.EventSelection event_selection = 4; - /** Numeric timezone offset for message count, day grouping. Optional. */ + /* Numeric timezone offset for message count, day grouping. Optional. */ int32 time_zone_offset = 5; - /** Timezone string for message count, day grouping. Optional. */ + /* Timezone string for message count, day grouping. Optional. */ string time_zone = 6; } diff --git a/event-json-examples/README.md b/event-json-examples/README.md new file mode 100644 index 0000000..34ffb2a --- /dev/null +++ b/event-json-examples/README.md @@ -0,0 +1,5 @@ +# Event json examples + +This directory contains a selection of example json files for events. + +Json events can be received through webhook and MQTT, if the json content type is selected. diff --git a/event-json-examples/modem-message-body-parsed.json b/event-json-examples/modem-message-body-parsed.json new file mode 100644 index 0000000..6ec7ca1 --- /dev/null +++ b/event-json-examples/modem-message-body-parsed.json @@ -0,0 +1,29 @@ +{ + "modemMessageBodyParsed": { + "organization": "your-organization", + "modemNumber": "AAAA AAAA", + "modemExternalDeviceId": "AABBCCDDEEFFGGHH", + "messageId": "123123", + "sentAt": { + "timestamp": "2020-06-01T05:15:25.355Z", + "textual": "2020-06-01T05:15:25.355Z" + }, + "parserIdentifier": "hiber:20-AABBCC", + "parserName": "text", + "parsedMessage": { + "text": "example" + }, + "tags": [{ + "id": "1", + "label": { + "name": "example-tag" + } + }], + "title": "A message from modem AAAA AAAA was parsed by body parser hiber:20-AABBCC.", + "description": "Message 123123 from modem AAAA AAAA was parsed by body parser hiber:20-AABBCC:\n\n{\"text\":\"example\"}\n", + "time": { + "timestamp": "2020-06-01T09:19:29.299Z", + "textual": "2020-06-01T09:19:29.299Z" + } + } +} diff --git a/event-json-examples/modem-message-body-received.json b/event-json-examples/modem-message-body-received.json new file mode 100644 index 0000000..ff21997 --- /dev/null +++ b/event-json-examples/modem-message-body-received.json @@ -0,0 +1,28 @@ +{ + "modemMessageBodyReceived": { + "organization": "your-organization", + "modemNumber": "AAAA AAAA", + "modemExternalDeviceId": "AABBCCDDEEFFGGHH", + "messageId": "123123", + "sentAt": { + "timestamp": "2020-06-01T05:15:25.355Z", + "textual": "2020-06-01T05:15:25.355Z" + }, + "body": { + "bytes": "ZXhhbXBsZQ==", + "hex": "6578616D706C65" + }, + "tags": [{ + "id": "1", + "label": { + "name": "example-tag" + } + }], + "title": "New message from modem AAAA AAAA was received. It was sent at 2020-06-01T05:15:25.355Z.", + "description": "A new message from modem AAAA AAAA was sent at 2020-06-01T05:15:25.355Z\n:\nIt contained the following body (hex):\n6578616D706C65\n", + "time": { + "timestamp": "2020-06-01T09:19:29.299Z", + "textual": "2020-06-01T09:19:29.299Z" + } + } +} diff --git a/event-json-examples/modem-message-received.json b/event-json-examples/modem-message-received.json new file mode 100644 index 0000000..70430f8 --- /dev/null +++ b/event-json-examples/modem-message-received.json @@ -0,0 +1,49 @@ +{ + "modemMessageReceived": { + "organization": "your-organization", + "modemNumber": "AAAA AAAA", + "message": { + "modemNumber": "AAAA AAAA", + "sentAt": { + "timestamp": "2020-06-01T05:15:25.355Z", + "textual": "2020-06-01T05:15:25.355Z" + }, + "location": { + "latitude": 20.222, + "longitude": 30.33299 + }, + "body": "ZXhhbXBsZQ==", + "receivedAt": { + "timestamp": "2020-06-01T09:19:29.299Z", + "textual": "2020-06-01T09:19:29.299Z" + }, + "messageId": "123123", + "bodyBytes": { + "bytes": "ZXhhbXBsZQ==", + "hex": "6578616D706C65" + }, + "bodyParsed": [{ + "parserId": 123, + "parserName": "text", + "result": { + "text": "example" + }, + "parserIdentifier": "hiber:20-AABBCC" + }], + "bodyParsedSuccessfully": true + }, + "tags": [{ + "id": "1", + "label": { + "name": "example-tag" + } + }], + "title": "New test message from modem AAAA AAAA was received. It was sent at 2020-06-01 05:15:25Z.", + "description": "A new test message from modem AAAA AAAA was received and decrypted at 2020-06-01 09:19:29.299Z:\nThe message was sent at 2020-04-14 04:22:00Z with location (20.222,30.33299).\nIt contained the following body (hex): \n 6578616D706C65\n\nIts body was parsed by:\n - text: {\"text\":\"example\"}\n", + "time": { + "timestamp": "2020-06-01T09:19:29.299Z", + "textual": "2020-06-01T09:19:29.299Z" + }, + "modemExternalDeviceId": "AABBCCDDEEFFGGHH" + } +} diff --git a/event.proto b/event.proto index cbdcd8e..92b020a 100644 --- a/event.proto +++ b/event.proto @@ -2,11 +2,15 @@ syntax = "proto3"; package hiber.event; +import "google/protobuf/struct.proto"; + import "base.proto"; import "integration_aws_iot.proto"; import "integration_mqtt.proto"; import "modem.proto"; import "modem_claim.proto"; +import "modem_message_body_parser.proto"; +import "modem_message_body_parser_automatic_assignment.proto"; import "modem_transfer.proto"; import "organization.proto"; import "publisher.proto"; @@ -42,13 +46,24 @@ message Event { ModemEvent.ModemActivatedEvent modem_activated = 36; ModemEvent.ModemStaleEvent modem_stale = 3; ModemEvent.MessageEvent.ModemMessageReceivedEvent modem_message_received = 4; + ModemEvent.MessageEvent.ModemMessageBodyReceivedEvent modem_message_body_received = 44; + ModemEvent.MessageEvent.ModemMessageBodyParsedEvent modem_message_body_parsed = 45; ModemEvent.MessageEvent.ModemMessageDroppedEvent modem_message_dropped = 5; ModemEvent.MessageEvent.ModemMessageDelayedEvent modem_message_delayed = 6; ModemEvent.MessageEvent.ModemMessageCannotBeParsedEvent modem_message_cannot_be_parsed = 7; + ModemEvent.MessageBodyParserEvent.CreatedEvent modem_message_body_parser_created = 46; + ModemEvent.MessageBodyParserEvent.UpdatedEvent modem_message_body_parser_updated = 47; + ModemEvent.MessageBodyParserEvent.DeletedEvent modem_message_body_parser_deleted = 48; + ModemEvent.MessageBodyParserEvent.AutomaticAssignmentEvent.CreatedEvent modem_message_body_parser_automatic_assignment_created = 49; + ModemEvent.MessageBodyParserEvent.AutomaticAssignmentEvent.UpdatedEvent modem_message_body_parser_automatic_assignment_updated = 50; + ModemEvent.MessageBodyParserEvent.AutomaticAssignmentEvent.DeletedEvent modem_message_body_parser_automatic_assignment_deleted = 51; + ModemEvent.MessageBodyParserEvent.AssignedEvent modem_message_body_parser_assigned = 52; + ModemEvent.MessageBodyParserEvent.UnassignedEvent modem_message_body_parser_unassigned = 53; UserEvent.UserAddedEvent user_added = 8; UserEvent.UserRemovedEvent user_removed = 9; UserEvent.UserInvitedEvent user_invited = 41; UserEvent.UserAccessRequestEvent user_access_request = 10; + UserEvent.UserValidationUpdatedEvent user_validation_updated = 54; ModemTransferEvent.ModemTransferStartedEvent modem_transfer_started = 15; ModemTransferEvent.ModemTransferCancelledEvent modem_transfer_cancelled = 16; ModemTransferEvent.ModemTransferReceivedEvent modem_transfer_received = 17; @@ -88,7 +103,7 @@ message Event { reserved 18; Duration health_warning_period = 19; Timestamp time = 4; - repeated hiber.tag.Tag tags = 5; + repeated tag.Tag tags = 5; string title = 6; string description = 7; } @@ -101,7 +116,7 @@ message Event { string modem_number = 2; Location location = 3; Timestamp time = 4; - repeated hiber.tag.Tag tags = 5; + repeated tag.Tag tags = 5; string title = 6; string description = 7; } @@ -115,7 +130,7 @@ message Event { int32 maximum_inactivity_period = 3; Timestamp time = 4; Timestamp last_message = 5; - repeated hiber.tag.Tag tags = 6; + repeated tag.Tag tags = 6; string title = 7; string description = 8; } @@ -131,41 +146,116 @@ message Event { uint64 message_id = 3; Timestamp time = 4; Timestamp sent_at = 10; - repeated hiber.tag.Tag tags = 7; + repeated tag.Tag tags = 7; string title = 8; string description = 9; } message MessageEvent { - /* This event is generated whenever a message comes in, after is has been decrypted. + /* This event is generated whenever a message comes in, after is has been decrypted + * and parsed (if any body parsers are configured for the modem). + * * It contains the relevant data in the message object, including location and the * user-defined body. + * * If any body parser(s) are configured for the modem, the modem message object also contains * a ParsedBody for each of them. */ message ModemMessageReceivedEvent { string organization = 1; string modem_number = 2; - hiber.modem.ModemMessage message = 3; - repeated hiber.tag.Tag tags = 4; string modem_external_device_id = 8; + + /* The received message, including parsed body. */ + modem.ModemMessage message = 3; + + /* The modem's tags. */ + repeated tag.Tag tags = 4; + string title = 5; string description = 6; Timestamp time = 7; } - /* Every message has a sequence marker. When we detect a jump in the sequence number, we can determine whether we - * missed a message (or even multiple messages). Typically, this is caused by interference between the modem and - * the satellite. Note that this event is only generated when a message comes in. If no messages come in for a - * certain period, the ModemStaleEvent is used. + /* This lightweight event is generated whenever a message comes in, after is has been decrypted. */ + message ModemMessageBodyReceivedEvent { + string organization = 1; + string modem_number = 2; + string modem_external_device_id = 3; + + /* Id of the message that was parsed. */ + uint64 message_id = 4; + + /* Time the message was sent from the modem. */ + Timestamp sent_at = 5; + + /* Message body convenience object. */ + BytesOrHex body = 6; + + /* The modem's tags. */ + repeated tag.Tag tags = 7; + + string title = 8; + string description = 9; + Timestamp time = 10; + } + + /* This event is generated whenever a message is parsed successfully by an assigned body parser. + * If multiple body parsers are assigned to a modem, multiple ModemMessageParsedEvent events will + * be produced by an incoming message. + * For the total result of all assigned parsers, see the ModemMessageReceivedEvent, which is produced + * after all body parsers have been applied. + */ + message ModemMessageBodyParsedEvent { + string organization = 1; + string modem_number = 2; + string modem_external_device_id = 3; + + /* Id of the message that was parsed. */ + uint64 message_id = 4; + + /* Time the message was sent from the modem. */ + Timestamp sent_at = 5; + + /* The identifier of the parser that parsed the body. */ + string parser_identifier = 6; + + /* The name of the parser that parsed the body. */ + string parser_name = 7; + + /* The resulting json from parsing the message body. */ + google.protobuf.Struct parsed_message = 8; + + /* The modem's tags. */ + repeated tag.Tag tags = 9; + + string title = 10; + string description = 11; + Timestamp time = 12; + } + + /* Every message has a sequence marker. When we detect a jump in the sequence number, + * we can determine whether we missed a message (or even multiple messages). + * Typically, this is caused by interference between the modem and the satellite. + * Note that this event is only generated when a message comes in. + * If no messages come in for a certain period, the ModemStaleEvent is used. */ message ModemMessageDroppedEvent { string organization = 1; string modem_number = 2; + + /* The amount of dropped messages between the previous message and this message. */ int32 dropped_messages = 3; - hiber.modem.ModemMessage message = 4; - repeated hiber.tag.Tag tags = 5; + + /* The message that produced this event. + * Note that this is a reduced version of the message, and may omit parsed body. + */ + modem.ModemMessage message = 4; + + /* The modem's tags at the time this message was received. */ + repeated tag.Tag tags = 5; + Health modem_health = 6; string title = 7; string description = 8; @@ -179,9 +269,18 @@ message Event { message ModemMessageDelayedEvent { string organization = 1; string modem_number = 2; - hiber.modem.ModemMessage message = 3; + + /* The message that produced this event. + * Note that this is a reduced version of the message, and may omit parsed body. + */ + modem.ModemMessage message = 3; + + /* The amount of seconds the message was delayed, if it is more than 1 day. */ int64 delay_seconds = 4; - repeated hiber.tag.Tag tags = 5; + + /* The modem's tags at the time this message was received. */ + repeated tag.Tag tags = 5; + Health modem_health = 6; string title = 7; string description = 8; @@ -197,69 +296,159 @@ message Event { uint64 modem_message_id = 3; Timestamp time = 4; string reason = 5; - repeated hiber.tag.Tag tags = 6; + repeated tag.Tag tags = 6; string title = 7; string description = 8; } } + /* Events related to ModemMessageBodyParsers. */ + message MessageBodyParserEvent { + message CreatedEvent { + string organization = 1; + modem.message.bodyparser.ModemMessageBodyParser created = 2; + string title = 3; + string description = 4; + Timestamp time = 5; + } + + message UpdatedEvent { + string organization = 1; + UpdateClearableString updated_name = 2; + UpdateClearableString updated_content_ksy = 3; + modem.message.bodyparser.SimpleModemMessageBodyParser updated_simple_parser = 4; + Filter.ChildOrganizations.Update updated_available_to_child_organizations = 5; + string title = 6; + string description = 7; + Timestamp time = 8; + } + + message DeletedEvent { + string organization = 1; + string deleted = 2; + string title = 3; + string description = 4; + Timestamp time = 5; + } + + message AssignedEvent { + string organization = 1; + repeated string parsers = 2; + repeated string modems = 3; + repeated tag.Tag tags = 4; + string title = 5; + string description = 6; + Timestamp time = 7; + } + + message UnassignedEvent { + string organization = 1; + repeated string parsers = 2; + repeated string modems = 3; + repeated tag.Tag tags = 4; + string title = 5; + string description = 6; + Timestamp time = 7; + } + + message AutomaticAssignmentEvent { + message CreatedEvent { + string organization = 1; + modem.message.bodyparser.ModemMessageBodyParserAutomaticAssignmentRule created = 2; + string title = 3; + string description = 4; + Timestamp time = 5; + } + + message UpdatedEvent { + message Update { + UpdateClearableString description = 1; + repeated string parsers_added = 2; + repeated string parsers_removed = 3; + Filter.Modems.Update modems = 4; + Filter.Tags.Update tags = 5; + repeated string manufacturers_added = 6; + repeated string manufacturers_removed = 7; + map peripherals_added = 8; + repeated string peripherals_removed = 9; + Filter.ChildOrganizations.Update apply_to_child_organizations = 10; + UpdateBoolean active = 11; + } + + string organization = 1; + Update updated = 2; + string title = 3; + string description = 4; + Timestamp time = 5; + } + + message DeletedEvent { + string organization = 1; + string deleted = 2; + string title = 3; + string description = 4; + Timestamp time = 5; + } + } + } + message ClaimEvent { message ModemClaimedEvent { string organization = 1; string modem_number = 2; - hiber.modem.ModemClaim claim = 3; + modem.ModemClaim claim = 3; Timestamp time = 4; string title = 5; string description = 6; - repeated hiber.tag.Tag tags = 7; + repeated tag.Tag tags = 7; } } } message ModemTransferEvent { message ModemTransferStartedEvent { - hiber.modem.ModemTransfer transfer = 1; + modem.ModemTransfer transfer = 1; string organization = 2; Timestamp time = 3; - repeated hiber.tag.Tag tags = 4; + repeated tag.Tag tags = 4; string title = 5; string description = 6; } message ModemTransferCancelledEvent { - hiber.modem.ModemTransfer transfer = 1; + modem.ModemTransfer transfer = 1; string organization = 2; Timestamp time = 3; - repeated hiber.tag.Tag tags = 4; + repeated tag.Tag tags = 4; string title = 5; string description = 6; } message ModemTransferReceivedEvent { - hiber.modem.ModemTransfer transfer = 1; + modem.ModemTransfer transfer = 1; string organization = 2; Timestamp time = 3; - repeated hiber.tag.Tag tags = 4; + repeated tag.Tag tags = 4; string title = 5; string description = 6; } message ModemTransferNotReceivedEvent { - hiber.modem.ModemTransfer transfer = 1; + modem.ModemTransfer transfer = 1; string organization = 2; Timestamp time = 3; - repeated hiber.tag.Tag tags = 4; + repeated tag.Tag tags = 4; string title = 5; string description = 6; } message ModemTransferReturnTransferStartedEvent { - hiber.modem.ModemTransfer return_transfer = 1; - hiber.modem.ModemTransfer original_transfer = 2; - repeated hiber.modem.ModemTransferReturnLine return_lines = 3; + modem.ModemTransfer return_transfer = 1; + modem.ModemTransfer original_transfer = 2; + repeated modem.ModemTransferReturnLine return_lines = 3; string organization = 4; Timestamp time = 5; - repeated hiber.tag.Tag tags = 6; + repeated tag.Tag tags = 6; string title = 7; string description = 8; } @@ -297,6 +486,14 @@ message Event { string title = 4; string description = 5; } + + message UserValidationUpdatedEvent { + string organization = 1; + string email_validation_regex = 2; + string title = 3; + string description = 4; + Timestamp time = 5; + } } message PublisherEvent { @@ -472,8 +669,7 @@ message Event { Timestamp time = 5; } - /** - * Message summary event that is sent when it has been configured for the organization. + /* Message summary event that is sent when it has been configured for the organization. * The period is configurable, using the EventConfiguration. * This event is disabled by default. */ @@ -567,24 +763,21 @@ message EventStreamRequest { EventSelection selection = 2; } -/** - * Configuration for configurable events. +/* Configuration for configurable events. * Some events are disable by default, or can be configured in different ways. Their configuration is available here. */ message EventConfiguration { - /** - * When enabled, this sends a ModemMessageSummaryEvent periodically. + /* When enabled, this sends a ModemMessageSummaryEvent periodically. * For example, you can configure the message summary to be a daily message, aligned to midnight in your time zone. */ message ModemMessageSummaryConfiguration { - /** The message summary event is disabled by default. */ + /* The message summary event is disabled by default. */ bool enabled = 1; - /** The period to send the message summary event for. The event can be sent every hour, day, etc. */ + /* The period to send the message summary event for. The event can be sent every hour, day, etc. */ Duration period = 2; - /** - * Align the period to given time. + /* Align the period to given time. * For example, an hourly period sends can be aligned to 0:00 to send every whole hour. * A weekly period can be aligned to send at a specific time on Monday by aligning to a timestamp on a Monday. * diff --git a/modem.proto b/modem.proto index 96e0f24..510b983 100644 --- a/modem.proto +++ b/modem.proto @@ -105,18 +105,18 @@ message Modem { */ Modem.Type type = 25; - /** Additional information when this modem is a gateway. */ + /* Additional information when this modem is a gateway. */ GatewayInfo gateway_info = 26; - /** Additional information when this modem is a connected device. */ + /* Additional information when this modem is a connected device. */ ConnectedDeviceInfo connected_device_info = 27; - /** Additional information when this modem is a gateway. */ + /* Additional information when this modem is a gateway. */ message GatewayInfo { int32 number_of_connected_devices = 1; } - /** Additional information when this modem is a connected device. */ + /* Additional information when this modem is a connected device. */ message ConnectedDeviceInfo { /* The gateways that this modem is connected to. * This field reflects the gateway that processed the last message for this modem. @@ -245,7 +245,7 @@ message ModemSelection { repeated Health health = 9; - /** Filter modems by status(es). Defaults to health statuses, excluding dead, lost or damaged modems. */ + /* Filter modems by status(es). Defaults to health statuses, excluding dead, lost or damaged modems. */ repeated Modem.Status status = 10; Transfers transfers = 11; @@ -293,15 +293,26 @@ message ModemMessage { * The result is stored either as a json object or an error string. */ message ParsedBody { - int32 parser_id = 1; + /* Id of the parser that was used, if the parser and modem are owned by the same organization. + * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique. + */ + int32 parser_id = 1 [deprecated = true]; + + /* Globally unique identifier of the parser that was used. */ + string parser_identifier = 6; + + /* Name of the parser that was used. */ string parser_name = 2; - reserved 3; - /* Result of parsing the body with this parser. */ - google.protobuf.Struct result = 5; + oneof parsed { + /* Error while parsing the message body. */ + string error = 4; + + /* Result of parsing the body with this parser. */ + google.protobuf.Struct result = 5; + } - /* Error while parsing the message body. */ - string error = 4; + reserved 3; } /* Unique message identifier. */ @@ -447,9 +458,9 @@ message MessageCountRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; ModemMessageSelection selection = 2; - /** Numeric timezone offset for day grouping. Optional. */ + /* Numeric timezone offset for day grouping. Optional. */ int32 time_zone_offset = 5; - /** Timezone string for day grouping. Optional. */ + /* Timezone string for day grouping. Optional. */ string time_zone = 6; } @@ -516,7 +527,14 @@ message UpdateModemStatusRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; - string modem_number = 2; + + /* Either pick a single modem to update. DEPRECATED, since ModemSelection is more flexible. */ + string modem_number = 2 [deprecated = true]; + + /* Or a modem selection. */ + ModemSelection modem_selection = 4; + + /* The new status for the modem(s). */ Modem.Status update_status = 3; } diff --git a/modem_message_body_parser.proto b/modem_message_body_parser.proto index 67c0742..044ddbe 100644 --- a/modem_message_body_parser.proto +++ b/modem_message_body_parser.proto @@ -24,59 +24,74 @@ service ModemMessageBodyParserService { rpc Test (TestModemMessageBodyParserRequest) returns (TestModemMessageBodyParserRequest.Response); rpc Retry (RetryModemMessageBodyParsing.Request) returns (RetryModemMessageBodyParsing.Response); - rpc ListAssignedParsers (ListAssignedParsersRequest) returns (ListAssignedParsersRequest.Response); - rpc AssignToModems (AssignModemMessageBodyParserToModemsRequest) returns (AssignModemMessageBodyParserToModemsRequest.Response); - rpc RemoveFromModems (RemoveModemMessageBodyParserFromModemsRequest) returns (RemoveModemMessageBodyParserFromModemsRequest.Response); + /* [DEPRECATED] Use ModemMessageBodyParserAssignmentService instead. */ + rpc ListAssignedParsers (ListAssignedParsersRequest) returns (ListAssignedParsersRequest.Response) { + option deprecated = true; + }; + /* [DEPRECATED] Use ModemMessageBodyParserAssignmentService instead. */ + rpc AssignToModems (AssignModemMessageBodyParserToModemsRequest) returns (AssignModemMessageBodyParserToModemsRequest.Response) { + option deprecated = true; + }; + /* [DEPRECATED] Use ModemMessageBodyParserAssignmentService instead. */ + rpc RemoveFromModems (RemoveModemMessageBodyParserFromModemsRequest) returns (RemoveModemMessageBodyParserFromModemsRequest.Response) { + option deprecated = true; + }; } -/** Modem message body parser. This defines a parsing strategy for the body of a message. - * A parser can be defined in two ways: using a .ksy (Kaitai struct) file or using the simple parser. - */ +/* Modem message body parser. This defines a parsing strategy for the body of a message. + * A parser can be defined in two ways: using a .ksy (Kaitai struct https://kaitai.io/) file or using the simple parser. + */ message ModemMessageBodyParser { - /* A modem message body parser is provided when it has a Provided identifier. - * A parent organization may provide parser to your organization based on your use case and agreements. - */ - message Provided { - int64 parser_id = 1; - string provider = 2; - } - /* A modem message body parser with this object is available to child organizations. - * This means the child organization sees a Provided identifier for this parser, and can use it, - * but not update or delete it. - * Parsers available to child organizations get a globally unique id, different from your own id for the parser. + * This means the child organization can use it, but not update or delete it. */ message AvailableToChildOrganizations { Filter.ChildOrganizations child_organizations = 1; - int64 parser_id_for_child_organizations = 2; } - /* Either the id of a parser you created, or the Provided block for a parser that was provided to you. */ - oneof identifier { - /* The id of a parser you created by uploading a .ksy file or creating a simple parser specification. */ - int32 id = 1; + /* The id for this parser within your organization. If you do not own this parser, this field will ot be set. + * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique. + */ + int32 id = 1 [deprecated = true]; - /* The id of a parser provided to you by a parent organization. */ - Provided provided_parser_id = 5; - } + /* The globally unique identifier for this parser. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth parser created by that organization). + */ + string identifier = 7; + + /* The organization that created the parser. */ + string organization = 8; + /* The name for this parser. */ string name = 2; + + /* The content of this parsers script. + * If simple_parser is set, this content is generated from that definition. + * This field may be omitted on demand to save data in the list call. + * + * See Kaitai struct (https://kaitai.io/) for more information about the ksy format. + */ string content_ksy = 3; - /* The simple parser this .ksy was generated from, if it was generated from a simple parser. */ + /* The simple parser this .ksy was generated from, if it was generated from a simple parser. + * This field may be omitted on demand to save data in the list call. + */ SimpleModemMessageBodyParser simple_parser = 4; - /** If set, this parser is available to your child organizations, as a Provided parser. */ + /* If set, this parser is available to your child organizations, as a Provided parser. */ AvailableToChildOrganizations available_to_child_organizations = 6; + + reserved 5; } -/** Simple modem message body parser. This can be used a convenient way to create a .ksy parser. */ +/* Simple modem message body parser. This can be used a convenient way to create a .ksy parser. */ message SimpleModemMessageBodyParser { message Field { - /** Field name. This is a reduced to a value containing only lowercase letters, numbers and underscores. */ + /* Field name. This is a reduced to a value containing only lowercase letters, numbers and underscores. */ string name = 1; - /** A short, single line description of the field. */ + /* A short, single line description of the field. */ string documentation = 2; oneof type { @@ -85,29 +100,29 @@ message SimpleModemMessageBodyParser { Bytes bytes = 5; String string = 6; - /** Specify an expected magic sequence (some bytes that are always the same). */ + /* Specify an expected magic sequence (some bytes that are always the same). */ bytes magic = 7; - /** Specify a custom type name. */ + /* Specify a custom type name. */ string custom_type = 8; } message Integer { - /** Specifies the size of this integer in bytes. */ + /* Specifies the size of this integer in bytes. */ int32 size_bytes = 3; - /** Specifies whether this integer is signed or unsigned. */ + /* Specifies whether this integer is signed or unsigned. */ bool signed = 4; - /** Specifies endian encoding for this field. This can be omitted if default endianness specified. */ + /* Specifies endian encoding for this field. This can be omitted if default endianness specified. */ Endian endian = 5; } message Float { - /** Specifies the size of this floating point number in bytes. */ + /* Specifies the size of this floating point number in bytes. */ int32 size_bytes = 3; - /** Specifies endian encoding for this field. This can be omitted if default endianness specified. */ + /* Specifies endian encoding for this field. This can be omitted if default endianness specified. */ Endian endian = 5; } @@ -118,30 +133,30 @@ message SimpleModemMessageBodyParser { message String { DelimitedSize size = 3; - /** Specifies encoding for the string. This can be omitted if default encoding specified. */ + /* Specifies encoding for the string. This can be omitted if default encoding specified. */ string encoding = 4; } } - /** Delimited size definition, used for Bytes and Text. */ + /* Delimited size definition, used for Bytes and Text. */ message DelimitedSize { oneof size { - /** Specifies the number of bytes in this field. */ + /* Specifies the number of bytes in this field. */ int32 size_bytes = 1; - /** Specifies that this field parses all bytes until the end of the stream. */ + /* Specifies that this field parses all bytes until the end of the stream. */ bool end_of_stream = 2; - /** Specifies the number of bytes in this field using the value of an Integer field. + /* Specifies the number of bytes in this field using the value of an Integer field. * This integer field must be parsed before this field is parsed. */ string field_name = 3; } - /** Specify a terminator that marks the point the field terminates, optionally, - * and we should continue to the next field. This is typically a single byte (i.e. 0x00). - * This can be combined with a size to limit the amounts of bytes that are parsed. - */ + /* Specify a terminator that marks the point the field terminates, optionally, + * and we should continue to the next field. This is typically a single byte (i.e. 0x00). + * This can be combined with a size to limit the amounts of bytes that are parsed. + */ bytes terminator = 4; } @@ -151,59 +166,55 @@ message SimpleModemMessageBodyParser { BIG_ENDIAN = 2; } - /** Parser name. - * When this structure is used as a custom type inside a parser, this name is a reduced to - * a value containing only lowercase letters, numbers and underscores, like field names. - */ + /* Parser name. + * When this structure is used as a custom type inside a parser, this name is a reduced to + * a value containing only lowercase letters, numbers and underscores, like field names. + */ string name = 1; - /** A short, single line description of the field. */ + /* A short, single line description of the field. */ string documentation = 2; - /** The fields in this object. */ + /* The fields in this object. */ repeated Field fields = 3; - /** Sets a default endianness for this parser's fields and any fields in custom types. */ + /* Sets a default endianness for this parser's fields and any fields in custom types. */ Endian default_endian = 4; - /** Sets a default string encoding for this parser's fields and any fields in custom types. */ + /* Sets a default string encoding for this parser's fields and any fields in custom types. */ string default_text_encoding = 5; - /** A list of custom types used for custom types fields. - * Each is effectively a simple parser, and can have its own custom types again, which can only be used within - * that parser structure. - * The parser name is used for custom type fields. - */ + /* A list of custom types used for custom types fields. + * Each is effectively a simple parser, and can have its own custom types again, which can only be used within + * that parser structure. + * The parser name is used for custom type fields. + */ repeated SimpleModemMessageBodyParser custom_types = 6; } message ModemMessageBodyParserSelection { - message SelectIdentifier { - oneof identifier { - int32 id = 1; - int64 provided_parser_id = 2; - } - } - /** Filter parsers by your own parser ids. */ - repeated int32 ids = 1; + repeated int32 ids = 1 [deprecated = true]; - /** Filter parsers by a combination of your own parser ids and provided parser ids. */ - repeated SelectIdentifier identifiers = 7; + /* Filter parsers by their identifiers. */ + repeated string identifiers = 8; + /* Find parsers by searching for this text in the name, content_ksy or simple parser definition. */ string search = 2; - /** Only return simple parsers, created using SimpleModemMessageBodyParser. */ + /* Only return simple parsers, created using SimpleModemMessageBodyParser. */ bool only_simple = 3; - /** Only return parsers created from an uploaded .ksy file. */ + /* Only return parsers created from an uploaded .ksy file. */ bool only_ksy_file = 4; - /** Exclude parsers that were provided (those that you did not create yourself). */ - bool exclude_provided_parsers = 5; + /* Exclude parsers that are not owned by your organization (those that you did not create yourself). */ + bool only_owned_parsers = 5; + + /* Only return parsers that were created by the given parent organizations. */ + repeated string owner_organizations = 6; - /** Only return parsers that were provided by the given parent organization. */ - repeated string providers = 6; + reserved 7; } message ListModemMessageBodyParsersRequest { @@ -217,6 +228,9 @@ message ListModemMessageBodyParsersRequest { string organization = 1; ModemMessageBodyParserSelection selection = 2; Pagination pagination = 3; + + /* Whether to omit the content in the resulting ModemMessageBodyParsers. */ + bool exclude_content = 4; } /* Upload a new body parser from a .ksy file. @@ -228,7 +242,11 @@ message ListModemMessageBodyParsersRequest { message UploadModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; + + /* A descriptive name for this parser. */ string name = 2; + + /* The ksy definition for this parser. */ string content_ksy = 3; } @@ -241,7 +259,19 @@ message UploadModemMessageBodyParserRequest { message UpdateUploadedModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; - int32 id = 2; + + /* The identifier of the parser that should be updated. + * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique. + */ + int32 id = 2 [deprecated = true]; + + /* The identifier of the parser that should be updated. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth parser created by that organization). + */ + string identifier = 4; + + /* The new ksy definition for this parser. */ string content_ksy = 3; } @@ -256,21 +286,60 @@ message CreateSimpleModemMessageBodyParserRequest { message UpdateSimpleModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; - int32 id = 2; + + /* The identifier of the parser that should be updated. + * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique. + */ + int32 id = 2 [deprecated = true]; + + /* The identifier of the parser that should be updated. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth parser created by that organization). + */ + string identifier = 4; + SimpleModemMessageBodyParser parser = 3; } message RenameModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; - int32 id = 2; + + /* The identifier of the parser that should be updated. + * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique. + */ + int32 id = 2 [deprecated = true]; + + /* The identifier of the parser that should be updated. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth parser created by that organization). + */ + string identifier = 4; + + /* The new name for this parser. */ string name = 3; } +/* Update the child availability for a parser. + * Parsers can be made available to child organizations, which means that they can be viewed in, + * and assigned to modems in, child organizations. + */ message UpdateChildOrganizationAvailabilityRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; - int32 id = 2; + + /* The identifier of the parser that should be updated. + * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique. + */ + int32 id = 2 [deprecated = true]; + + /* The identifier of the parser that should be updated. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth parser created by that organization). + */ + string identifier = 4; + + /* The new child organization availability filter for this parser. */ Filter.ChildOrganizations available_to_child_organizations = 3; } @@ -280,9 +349,19 @@ message DeleteModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; + + /* A selection of parsers to be deleted. */ ModemMessageBodyParserSelection selection = 2; } +/* Test a parsers with a message. + * This method provides a bunch of options and can be used in multiple ways: + * - Test a real message or an uploaded message body. + * - Test using an existing parser, an ksy definition or a simple parser definition. + * + * This can be used to test a parser with a modem's past messages, before assigning it, + * or while developing a parser to validate it with an expected body. + */ message TestModemMessageBodyParserRequest { message Response { oneof result { @@ -294,23 +373,45 @@ message TestModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; + /* Either an existing parser, an uploaded ksy definition or a simple parser definition to test. */ oneof parser { + /* The identifier of the parser you want to test. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth parser created by that organization). + */ + string identifier = 7; + + /* A ksy definition you want to test. */ string content_ksy = 2; + + /* A simple parser definition you want to test. */ SimpleModemMessageBodyParser simple_parser = 3; - ModemMessageBodyParserSelection.SelectIdentifier identifier = 6; } + /* Either a real message or a given message body. */ oneof data { + /* A byte array (message body) to parse. */ BytesOrHex parse_bytes = 4; + + /* The id of an existing message, testing the parser on its body. */ uint64 modem_message_id = 5; } + + reserved 6; } +/* Retry a message, parsing it with all the currently assigned parsers that are in the given selection. + * If the message was previously parsed by any of those parsers, the previous result is replaced. + */ message RetryModemMessageBodyParsing { message Request { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; + + /* The messages to parse. */ repeated uint64 modem_message_ids = 2; + + /* A selection of parsers to apply, if they are assigned. */ ModemMessageBodyParserSelection parser_selection = 3; } @@ -319,46 +420,63 @@ message RetryModemMessageBodyParsing { } } +/* [DEPRECATED] Use ModemMessageBodyParserAssignmentService instead. */ message ListAssignedParsersRequest { + option deprecated = true; + message Response { + option deprecated = true; + message AssignedParsers { - string modem_number = 1; - repeated ModemMessageBodyParser parsers = 2; + option deprecated = true; + + string modem_number = 1 [deprecated = true]; + repeated ModemMessageBodyParser parsers = 2 [deprecated = true]; } - repeated AssignedParsers assigned_parsers = 1; - ListAssignedParsersRequest request = 2; - Pagination.Result pagination = 3; + repeated AssignedParsers assigned_parsers = 1 [deprecated = true]; + ListAssignedParsersRequest request = 2 [deprecated = true]; + Pagination.Result pagination = 3 [deprecated = true]; } - string organization = 1; - ModemMessageBodyParserSelection selection = 2; - modem.ModemSelection modem_selection = 3; - Pagination pagination = 4; + string organization = 1 [deprecated = true]; + ModemMessageBodyParserSelection selection = 2 [deprecated = true]; + modem.ModemSelection modem_selection = 3 [deprecated = true]; + Pagination pagination = 4 [deprecated = true]; } +/* [DEPRECATED] Use ModemMessageBodyParserAssignmentService instead. */ message AssignModemMessageBodyParserToModemsRequest { + option deprecated = true; + message Response { - repeated ListAssignedParsersRequest.Response.AssignedParsers assigned_parsers = 3; - AssignModemMessageBodyParserToModemsRequest request = 2; + option deprecated = true; + + repeated ListAssignedParsersRequest.Response.AssignedParsers assigned_parsers = 3 [deprecated = true]; + AssignModemMessageBodyParserToModemsRequest request = 2 [deprecated = true]; reserved 1; } /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ - string organization = 1; - ModemMessageBodyParserSelection selection = 2; - modem.ModemSelection modem_selection = 3; + string organization = 1 [deprecated = true]; + ModemMessageBodyParserSelection selection = 2 [deprecated = true]; + modem.ModemSelection modem_selection = 3 [deprecated = true]; } +/* [DEPRECATED] Use ModemMessageBodyParserAssignmentService instead. */ message RemoveModemMessageBodyParserFromModemsRequest { + option deprecated = true; + message Response { - repeated ListAssignedParsersRequest.Response.AssignedParsers assigned_parsers = 3; - RemoveModemMessageBodyParserFromModemsRequest request = 2; + option deprecated = true; + + repeated ListAssignedParsersRequest.Response.AssignedParsers assigned_parsers = 3 [deprecated = true]; + RemoveModemMessageBodyParserFromModemsRequest request = 2 [deprecated = true]; reserved 1; } /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ - string organization = 1; - ModemMessageBodyParserSelection selection = 2; - modem.ModemSelection modem_selection = 3; + string organization = 1 [deprecated = true]; + ModemMessageBodyParserSelection selection = 2 [deprecated = true]; + modem.ModemSelection modem_selection = 3 [deprecated = true]; } diff --git a/modem_message_body_parser_assignment.proto b/modem_message_body_parser_assignment.proto new file mode 100644 index 0000000..f17e2fb --- /dev/null +++ b/modem_message_body_parser_assignment.proto @@ -0,0 +1,122 @@ +syntax = "proto3"; + +package hiber.modem.message.bodyparser; + +import "base.proto"; +import "modem.proto"; +import "modem_message_body_parser.proto"; +import "modem_message_body_parser_automatic_assignment.proto"; + +option java_multiple_files = false; +option java_package = "global.hiber.api.grpc.modem.message.bodyparser"; +option java_outer_classname = "ModemMessageBodyParserAssignmentApi"; +option go_package = "hiber"; + +service ModemMessageBodyParserAssignmentService { + rpc List (ListAssignedModemMessageBodyParsers.Request) returns (ListAssignedModemMessageBodyParsers.Response); + rpc Assign (AssignModemMessageBodyParsersToModems.Request) returns (AssignModemMessageBodyParsersToModems.Response); + rpc Unassign (UnassignModemMessageBodyParsersFromModems.Request) returns (UnassignModemMessageBodyParsersFromModems.Response); +} + +/* The body parsers that are assigned to a modem, either directly or automatically. */ +message ModemMessageBodyParsersAssignment { + /* The modem number that has parsers assigned. */ + string modem_number = 1; + + /* The parsers assigned to this modem (both directly and automatic). */ + repeated ModemMessageBodyParser parsers = 2; + + /* The rules that were applied to assign these parsers to this modem. */ + repeated string rules_applied = 3; +} + +/* Selection for assigned parsers, to dynamically filter the assignments by body parsers, + * modems it applies to, rules that are used, the way it was assigned to the modem, etc. + */ +message ModemMessageBodyParsersAssignmentSelection { + /* Only return parsers that match the given selection. */ + ModemMessageBodyParserSelection parsers = 1; + + /* Only return parsers that have been assigned to the given modems. */ + modem.ModemSelection modems = 2; + + /* Only return parsers that have been assigned to the modem by one of these rules. + * This can also be used to include certain inactive rules, to test what they apply to, + * either in combination with active rules, or only that specific rule. + * To do so, either set include_inactive or only_inactive in ModemMessageBodyParserAutomaticAssignmentRuleSelection. + */ + ModemMessageBodyParserAutomaticAssignmentRuleSelection rules = 3; + + /* Only return parsers that have been directly assigned to the modem. */ + bool only_directly_assigned = 4; + + /* Only return parsers that have been assigned to the modem by a rule. */ + bool only_automatically_assigned = 5; + + /* If childOrganizations is configured to include child organizations, modems from child organizations + * can also be in the results, if the other conditions match. + */ + Filter.ChildOrganizations child_organizations = 6; + + /* Use onlyChildOrganizations to *only* see which selected modems have the selected parsers assigned + * in the selected child_organizations, excluding any modems in your organization. + */ + bool only_child_organizations = 7; +} + +/* List modems with assigned parsers, based on the selections and flags in the request. */ +message ListAssignedModemMessageBodyParsers { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + ModemMessageBodyParsersAssignmentSelection selection = 2; + Pagination pagination = 3; + + /* Whether to omit the parser content in the resulting ModemMessageBodyParsers, to save data. */ + bool exclude_content = 4; + } + + message Response { + repeated ModemMessageBodyParsersAssignment assigned_parsers_per_modem = 1; + Request request = 2; + Pagination.Result pagination = 3; + } +} + +/* Assign parser(s) to modem(s) directly. */ +message AssignModemMessageBodyParsersToModems { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The parser(s) to assign to the given modem(s) directly. */ + ModemMessageBodyParserSelection selection = 2; + + /* The modem(s) to assign the given parser(s) to. */ + modem.ModemSelection modem_selection = 3; + } + + message Response { + repeated ModemMessageBodyParsersAssignment directly_assigned_parsers_per_modem = 1; + Request request = 2; + } +} + +/* Unassign directly assigned parser(s) from modem(s). */ +message UnassignModemMessageBodyParsersFromModems { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The parser(s) to unassign from the given modem(s), if they are directly assigned. */ + ModemMessageBodyParserSelection selection = 2; + + /* The modem(s) to unassign the given parser(s) from. */ + modem.ModemSelection modem_selection = 3; + } + + message Response { + repeated ModemMessageBodyParsersAssignment directly_assigned_parsers_per_modem = 1; + Request request = 2; + } +} diff --git a/modem_message_body_parser_automatic_assignment.proto b/modem_message_body_parser_automatic_assignment.proto new file mode 100644 index 0000000..5ae931c --- /dev/null +++ b/modem_message_body_parser_automatic_assignment.proto @@ -0,0 +1,274 @@ +syntax = "proto3"; + +package hiber.modem.message.bodyparser; + +import "base.proto"; +import "modem.proto"; +import "modem_message_body_parser.proto"; + +option java_multiple_files = false; +option java_package = "global.hiber.api.grpc.modem.message.bodyparser"; +option java_outer_classname = "ModemMessageBodyParserAutomaticAssignmentApi"; +option go_package = "hiber"; + +service ModemMessageBodyParserAutomaticAssignmentService { + rpc List (ListBodyParserAutomaticAssignmentRules.Request) returns (ListBodyParserAutomaticAssignmentRules.Response); + rpc Create (CreateBodyParserAutomaticAssignmentRule.Request) returns (CreateBodyParserAutomaticAssignmentRule.Response); + rpc UpdateParsers (UpdateBodyParserAutomaticAssignmentParsers.Request) returns (UpdateBodyParserAutomaticAssignmentParsers.Response); + rpc UpdateDescription (UpdateBodyParserAutomaticAssignmentDescription.Request) returns (UpdateBodyParserAutomaticAssignmentDescription.Response); + rpc UpdateChildAvailability (UpdateBodyParserAutomaticAssignmentChildAvailability.Request) returns (UpdateBodyParserAutomaticAssignmentChildAvailability.Response); + + rpc Enable (EnableBodyParserAutomaticAssignmentRule.Request) returns (EnableBodyParserAutomaticAssignmentRule.Response); + rpc Disable (DisableBodyParserAutomaticAssignmentRule.Request) returns (DisableBodyParserAutomaticAssignmentRule.Response); + + rpc Delete (DeleteBodyParserAutomaticAssignmentRule.Request) returns (DeleteBodyParserAutomaticAssignmentRule.Response); +} + +/* A rule to assign a ModemMessageBodyParser to any number of modems automatically, based on varying criteria. + * + * For example, all modems with tag "parse-this" and a peripheral "sensor": "water-sensor-brand-x" can be + * assigned a parser for the data format for that peripheral. + * + * Criteria can be used and combined in a multitude of ways, but here are a few notable uses: + * - assign a parser to tag, so assigning it to modems is as easy as adding a tag to that modem + * - assign a parser to peripheral, so each modem with that peripheral gets that parser by default + * - blacklisting a parser from a tag, so you can set that tag to exclude a modem from being assigned that parser + * - blacklisting a parser from a set of modems, so you can exclude a set of modem from being assigned that parser + * - add a parser to devices you manufacture, and apply this to child organizations, so that all of your + * customers' modems are automatically assigned that parser + */ +message ModemMessageBodyParserAutomaticAssignmentRule { + /* A rule for automatic assignment of a body parser to modems. + * Each field in the this rule must match a modem for this rule to be applied. + * This means that the exclusion rules for modem and tag can be used to create a complex selection, + * like all modems with a tag, except for a specific list of modems. + * Or every modem with the given peripherals, except when you assign a tag to them (i.e. a "do-not-parse" tag). + * + * This also means you can make a rule that only excludes modems or tags. A rule that only excludes is considered + * a global exclude, and will override other rules assigning the excluded modem anyway. + * For example, a rule that excludes the tag "do-not-parse" for all parsers, will override any assignment by a rule + * if the modem has that tag. + */ + message AssignmentRule { + /* An alternative way to assign to modem directly, this field can be used to assign a parser to a set of modems. + * + * A rule that only excludes is considered a global exclude, and will override other rules assigning + * the excluded modem anyway. + * For example, a rule that excludes a modem for a set of parsers, will ensure the modem will never be assigned + * those parser automatically. + */ + Filter.Modems modems = 1; + + /* Assign parser to all modems that have the given tags. + * + * A rule that only excludes is considered a global exclude, and will override other rules assigning + * the excluded modem anyway. + * For example, a rule that excludes the tag "do-not-parse" for all parsers, will override any assignment + * by a rule if the modem has that tag. + */ + Filter.Tags tags = 2; + + /* Assign the parser to modems that have one of the given manufacturers. */ + repeated string manufacturer = 3; + + /* Assign the parser to modems that have one of the given peripherals. */ + map peripherals = 4; + } + + /* The identifier for this rule. + * The identifier consists of the name of the organization that created it and its id in that organization. + * For example my-organization:4 (the fourth assignment rule created by that organization). + */ + string identifier = 1; + + /* The organization that created and owns this rule. */ + string owner_organization = 2; + + /* A description for this rule. Use this to make clear why this rule is set up. */ + string description = 3; + + /* The parser that should be assigned when a modem matches this rule. */ + repeated string parsers = 4; + + /* The rules to use to select modems. */ + AssignmentRule rule = 5; + + /* Whether the rule is active. Rules can be disabled, or uploaded in a disabled state to test them. */ + bool active = 6; + + /* Apply this rule to modems belonging to the given child organizations as well. + * The selected parsers must be available to those child organizations. + * This does not work with tags, since they are organization-specific. + */ + Filter.ChildOrganizations apply_to_child_organizations = 7; +} + +message ModemMessageBodyParserAutomaticAssignmentRuleSelection { + /* Return assignment rules with the given identifiers. */ + repeated string assignment_rule_identifiers = 1; + + /* Return assignment rules with the given owner(s). */ + Filter.ChildOrganizations owner_organizations = 2; + + /* Search assignment rules. */ + string search = 3; + + /* Return assignment rules that assign one of the selected parsers. */ + ModemMessageBodyParserSelection assigns_parsers = 4; + + /* Return assignment rules that apply to the selected modems. */ + ModemSelection applies_to_modems = 5; + + /* Include inactive rules. */ + bool include_inactive = 6; + + /* Only return inactive rules. */ + bool only_inactive = 7; +} + +/* List automatic assignment rules. */ +message ListBodyParserAutomaticAssignmentRules { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + ModemMessageBodyParserAutomaticAssignmentRuleSelection selection = 2; + Pagination pagination = 3; + } + + message Response { + repeated ModemMessageBodyParserAutomaticAssignmentRule assignment_rules = 1; + Pagination.Result pagination = 2; + Request request = 3; + } +} + +/* Create a new automatic assignment rule. */ +message CreateBodyParserAutomaticAssignmentRule { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The parser to assign with this rule. */ + repeated string parsers = 2; + + /* A description for this rule. */ + string description = 3; + + /* The automatic assignment rule to apply. */ + ModemMessageBodyParserAutomaticAssignmentRule.AssignmentRule rule = 4; + + /* By default, the rule only applies to your organization. + * Use this filter to apply the rule to (some of) your child organizations as well. + */ + Filter.ChildOrganizations apply_to_child_organizations = 5; + + /* Whether the rules should be created in a disabled state. */ + bool disabled = 6; + } + + message Response { + ModemMessageBodyParserAutomaticAssignmentRule created = 1; + Request request = 2; + } +} + +/* Update the parsers assigned by an automatic assignment rule. */ +message UpdateBodyParserAutomaticAssignmentParsers { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The rule to update. */ + string assignment_rule_identifier = 2; + + /* Add the given parsers to the rule. */ + repeated string add_parsers = 3; + + /* Remove the given parsers from the rule. */ + repeated string remove_parsers = 4; + } + + message Response { + ModemMessageBodyParserAutomaticAssignmentRule updated = 1; + } +} + +/* Update the description of an automatic assignment rule. */ +message UpdateBodyParserAutomaticAssignmentDescription { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The rule to update. */ + string assignment_rule_identifier = 2; + + /* The updated description. */ + string description = 3; + } + + message Response { + ModemMessageBodyParserAutomaticAssignmentRule updated = 1; + } +} + +/* Update the child availability of an automatic assignment rule (child organizations that this rule applies to). */ +message UpdateBodyParserAutomaticAssignmentChildAvailability { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The rule to update. */ + string assignment_rule_identifier = 2; + + /* The new set of child organizations that this rule applies to. */ + Filter.ChildOrganizations update_apply_to_child_organizations = 6; + } + + message Response { + ModemMessageBodyParserAutomaticAssignmentRule updated = 1; + } +} + +/* Enable the given automatic assignment rule. */ +message EnableBodyParserAutomaticAssignmentRule { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The rule to enable. */ + string assignment_rule_identifier = 2; + } + + message Response { + ModemMessageBodyParserAutomaticAssignmentRule enabled = 1; + } +} + +/* Disable the given automatic assignment rule. */ +message DisableBodyParserAutomaticAssignmentRule { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The rule to disable. */ + string assignment_rule_identifier = 2; + } + + message Response { + ModemMessageBodyParserAutomaticAssignmentRule disabled = 1; + } +} + +/* Delete the given automatic assignment rule. */ +message DeleteBodyParserAutomaticAssignmentRule { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The rule to delete. */ + string assignment_rule_identifier = 2; + } + + message Response { + } +} diff --git a/token.proto b/token.proto index 8d1e9ab..bf1dcd0 100644 --- a/token.proto +++ b/token.proto @@ -51,6 +51,7 @@ message ListTokensRequest { message CreateTokenRequest { message Response { string token = 1; + Token created = 2; } /* Pick the organization to use (/impersonate). If unset, your default organization is used. */