0.51

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
 

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 {

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;
 }
 

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.

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"
+    }
+  }
+}

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"
+    }
+  }
+}

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"
+  }
+}