===========================
Data Event Formats - Levels
===========================


Summary
=======

CWMS needs an message structure to notify clients of location level-related events.

Opinions
========

Opinion 1
---------

Summary: Use the structures described below for location level-related events.

All messages will be published to the appropriate ``REALTIME_OPS`` topic. Subscribers can set up appropriate filters to receive the desired messages.

Author: Mike Perryman

Specified Levels
^^^^^^^^^^^^^^^^

Only values necessary to uniquely identify a specified level ("type", "specified_level_id") are required for SpecifiedLevelCreated, SpecifiedLevelUpdated,
and SpecifiedLevelDeleted messages.

**SpecifiedLevelCreated Message Structure**

+-----------------------+--------------------------------------------------------------------------------+
| Message Type          | Structure                                                                      |
+=======================+================================================================================+
| SpecifiedLevelCreated | +------------+----------------------+----------------------------------------+ |
|                       | | Value Type | Value Name           | Value                                  | |
|                       | +============+======================+========================================+ |
|                       | | String     | "type"               | "specified_level_created"              | |
|                       | +------------+----------------------+----------------------------------------+ |
|                       | | Object     | "specified_level_id" | The specified level identifier         | |
|                       | +------------+----------------------+----------------------------------------+ |
|                       | | String     | "description"        | The description of the specified level | |
|                       | +------------+----------------------+----------------------------------------+ |
+-----------------------+--------------------------------------------------------------------------------+

**Example SpecifiedLevelCreated message**

.. code-block:: json

    {
        "type": "specified_level_created",
        "specified_level_id": {
        	"office_id": "SWT",
        	"name": "24-hr Surveilance"
        },
        "description": "Level at which 24-hour surveillance is required"
    }

**SpecifiedLevelUpdated Message Structure**

+-----------------------+--------------------------------------------------------------------------------+
| Message Type          | Structure                                                                      |
+=======================+================================================================================+
| SpecifiedLevelUpdated | +------------+----------------------+----------------------------------------+ |
|                       | | Value Type | Value Name           | Value                                  | |
|                       | +============+======================+========================================+ |
|                       | | String     | "type"               | "specified_level_updated"              | |
|                       | +------------+----------------------+----------------------------------------+ |
|                       | | Object     | "specified_level_id" | The specified level identifier         | |
|                       | +------------+----------------------+----------------------------------------+ |
|                       | | String     | "description"        | The description of the specified level | |
|                       | +------------+----------------------+----------------------------------------+ |
+-----------------------+--------------------------------------------------------------------------------+

**Example SpecifiedLevelUpdated message**

.. code-block:: json

    {
        "type": "specified_level_updated",
        "specified_level_id": {
        	"office_id": "SWT",
        	"name": "24-hr Surveilance"
        },
        "description": "Lowest level at which 24-hour surveillance is required"
    }

**SpecifiedLevelDeleted Message Structure**

+-----------------------+--------------------------------------------------------------------------------+
| Message Type          | Structure                                                                      |
+=======================+================================================================================+
| SpecifiedLevelDeleted | +------------+----------------------+----------------------------------------+ |
|                       | | Value Type | Value Name           | Value                                  | |
|                       | +============+======================+========================================+ |
|                       | | String     | "type"               | "specified_level_deleted"              | |
|                       | +------------+----------------------+----------------------------------------+ |
|                       | | Object     | "specified_level_id" | The specified level identifier         | |
|                       | +------------+----------------------+----------------------------------------+ |
+-----------------------+--------------------------------------------------------------------------------+

**Example SpecifiedLevelDeleted message**

.. code-block:: json

    {
        "type": "specified_level_deleted",
        "specified_level_id": {
        	"office_id": "SWT",
        	"name": "24-hr Surveilance"
        },
    }

Location Levels
^^^^^^^^^^^^^^^

Only values necessary to uniquely identify a location level ("type", "location_level_id", "effective_time", and "virtual") are required for LocationLevelCreated,
LocationLevelUpdated, and LocationLevelDeleted messages.

If the location level has an attribute, "attribute_id", "attribute_value", and "attribute_name" are also required.

**LocationLevelCreated Message Structure**

+----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Message Type         | Structure                                                                                                                                                  |
+======================+============================================================================================================================================================+
| LocationLevelCreated | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | Value Type | Value Name            | Value                                                                                                             | |
|                      | +============+=======================+===================================================================================================================+ |
|                      | | String     | "type"                | "location_level_created"                                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | Object     | "location_level_id"   | The location level identifier                                                                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_id"        | The attribute identifier                                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | double     | "attribute_value"     | The value of the attribute                                                                                        | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_unit"      | The unit of the attribute                                                                                         | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "effective_time"      | The effective date/time of the location level in epoch milliseconds                                               | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | boolean    | "virtual"             | Whether the level is a virtual location level                                                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | double     | "constant_value"      | The value of the level if it is constant                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "constant_value_unit" | The unit of the constant value                                                                                    | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "interval_origin"     | The date/time of the beginning of any interval in epoch milliseconds if the level is regularly varying (seasonal) | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | int        | "interval_months"     | The calendar-based recurrence interval if the level is regularly varying (seasonal)                               | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | int        | "interval_minutes"    | The time-based recurrence interval if the level is regularly varying (seasonal)                                   | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "time_series_id"      | The identifier of the backing time series if the level is irregularly varying                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "expiration_time"     | The date/time the level expires in epoch milliseconds                                                             | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "level_comment"       | The comment on the location level                                                                                 | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_comment"   | The comment on the level attribute                                                                                | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
+----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+

**Example LocationLevelCreated message**

.. code-block:: json

    {
        "type": "location_level_created",
        "location_level_id": {
        	"office_id": "SWT",
        	"name": "Keystone.Elev.Inst.0.24-hr Surveillance"
        },
        "effective_time": 1782190800000,
        "virtual": false,
        "constant_value": 727.4,
        "constant_value_unit": "ft"
    }

**LocationLevelUpdated Message Structure**

+----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Message Type         | Structure                                                                                                                                                  |
+======================+============================================================================================================================================================+
| LocationLevelUpdated | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | Value Type | Value Name            | Value                                                                                                             | |
|                      | +============+=======================+===================================================================================================================+ |
|                      | | String     | "type"                | "location_level_updated"                                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | Object     | "location_level_id"   | The location level identifier                                                                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_id"        | The attribute identifier                                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | double     | "attribute_value"     | The value of the attribute                                                                                        | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_unit"      | The unit of the attribute                                                                                         | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "effective_time"      | The effective date/time of the location level in epoch milliseconds                                               | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | boolean    | "virtual"             | Whether the level is a virtual location level                                                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | double     | "constant_value"      | The value of the level if it is constant                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "constant_value_unit" | The unit of the constant value                                                                                    | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "interval_origin"     | The date/time of the beginning of any interval in epoch milliseconds if the level is regularly varying (seasonal) | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | int        | "interval_months"     | The calendar-based recurrence interval if the level is regularly varying (seasonal)                               | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | int        | "interval_minutes"    | The time-based recurrence interval if the level is regularly varying (seasonal)                                   | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "time_series_id"      | The identifier of the backing time series if the level is irregularly varying                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "expiration_time"     | The date/time the level expires in epoch milliseconds                                                             | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "level_comment"       | The comment on the location level                                                                                 | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_comment"   | The comment on the level attribute                                                                                | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
+----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+

**Example LocationLevelUpdated message**

.. code-block:: json

    {
        "type": "location_level_updated",
        "location_level_id": {
        	"office_id": "SWT",
        	"name": "Keystone.Elev.Inst.0.24-hr Surveillance"
        },
        "effective_time": 1782190800000,
        "virtual": false,
        "constant_value": 727.4,
        "constant_value_unit": "ft",
        "level_comment": "Updated after embankment remediation"
    }

**LocationLevelDeleted Message Structure**

+----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Message Type         | Structure                                                                                                                                                  |
+======================+============================================================================================================================================================+
| LocationLevelDeleted | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | Value Type | Value Name            | Value                                                                                                             | |
|                      | +============+=======================+===================================================================================================================+ |
|                      | | String     | "type"                | "location_level_deleted"                                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | Object     | "location_level_id"   | The location level identifier                                                                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_id"        | The attribute identifier                                                                                          | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | double     | "attribute_value"     | The value of the attribute                                                                                        | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | String     | "attribute_unit"      | The unit of the attribute                                                                                         | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | long       | "effective_time"      | The effective date/time of the location level in epoch milliseconds                                               | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
|                      | | boolean    | "virtual"             | Whether the level is a virtual location level                                                                     | |
|                      | +------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+ |
+----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+

**Example LocationLevelDeleted message**

.. code-block:: json

    {
        "type": "location_level_deleted",
        "location_level_id": {
        	"office_id": "SWT",
        	"name": "Keystone.Elev.Inst.0.24-hr Surveillance"
        },
        "effective_time": 1782190800000,
        "virtual": false
    }

Decision Status
===============

Status: request for comments

References
==========