========================== Data Event Formats - Locks ========================== Summary ======= CWMS needs a message structure to notify clients of lock-related events. Opinions ======== Opinion 1 --------- Summary: Use the structures described below for lock-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 Locks ^^^^^ Only values necessary to uniquely identify a lock ("type", "lock_id"), and values necessary to minimally describe a lock ("project_id") are required for LockCreated and LockUpdated messages. **LockCreated Message Structure** +--------------+--------------------------------------------------------------------------------------------------------------------------------------+ | Message Type | Structure | +==============+======================================================================================================================================+ | LockCreated | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | Value Type | Value Name | Value | | | | +============+=======================+=============================================================================================+ | | | | String | "type" | "lock_created" | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | Object | "lock_id" | The lock identifier | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "project_id" | The identifier of the project to which the lock belongs | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "volume_per_lockage" | The volume of water released for each lockage | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "volume_unit" | The unit for volume | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "length" | The length of the lock | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "width" | The width of the lock | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "minimum_draft" | The minimum draft of the lock | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "normal_lift" | The normal elevation difference between the upstream and downstream pools | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "maximum_lift" | The maximum lift the lock can support | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "unit" | The unit of length, width, draft, and lift | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "gate_type" | The type of lock gate used (see table) | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | +--------------+--------------------------------------------------------------------------------------------------------------------------------------+ **Example LockCreated message** .. code-block:: json { "type": "lock_created", "lock_id": { "office_id": "SWT", "name": "Green LD2-Lock" }, "project_id": "Green LD2", "volume_per_lockage": 42.4, "volume_unit": "acft", "length": 600.0, "width": 110.0, "minimum_draft": 9.0, "normal_lift": 28.0, "maximum_lift": 35.0, "unit": "ft", "gate_type": "Single Chamber" } **LockUpdated Message Structure** +--------------+--------------------------------------------------------------------------------------------------------------------------------------+ | Message Type | Structure | +==============+======================================================================================================================================+ | LockUpdated | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | Value Type | Value Name | Value | | | | +============+=======================+=============================================================================================+ | | | | String | "type" | "lock_updated" | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | Object | "lock_id" | The lock identifier | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "project_id" | The identifier of the project to which the lock belongs | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "volume_per_lockage" | The volume of water released for each lockage | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "volume_unit" | The unit for volume | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "length" | The length of the lock | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "width" | The width of the lock | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "minimum_draft" | The minimum draft of the lock | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "normal_lift" | The normal elevation difference between the upstream and downstream pools | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | double | "maximum_lift" | The maximum lift the lock can support | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "unit" | The unit of length, width, draft, and lift | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | String | "gate_type" | The type of lock gate used (see table) | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | +--------------+--------------------------------------------------------------------------------------------------------------------------------------+ **Example LockUpdated message** .. code-block:: json { "type": "lock_updated", "lock_id": { "office_id": "SWT", "name": "Green LD2-Lock" }, "project_id": "Green LD2", "volume_per_lockage": 42.4, "volume_unit": "acft", "length": 600.0, "width": 110.0, "minimum_draft": 9.0, "normal_lift": 28.0, "maximum_lift": 35.0, "unit": "ft", "gate_type": "Single Chamber" } Only values necessary to uniquely identify a lock ("type", "lock_id") are required for LockDeleted messages. **LockDeleted Message Structure** +--------------+--------------------------------------------------------------------------------------------------------------------------------------+ | Message Type | Structure | +==============+======================================================================================================================================+ | LockDeleted | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | Value Type | Value Name | Value | | | | +============+=======================+=============================================================================================+ | | | | String | "type" | "lock_deleted" | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | | | | Object | "lock_id" | The lock identifier | | | | +------------+-----------------------+---------------------------------------------------------------------------------------------+ | +--------------+--------------------------------------------------------------------------------------------------------------------------------------+ **Example LockDeleted message** .. code-block:: json { "type": "lock_deleted", "lock_id": { "office_id": "SWT", "name": "Green LD2-Lock" } } **Gate Types Table** +-----------------+----------------------------------------------------+ | Gate Type | Description | +=================+====================================================+ | Single Chamber | A lock gate system with a single chamber | +-----------------+----------------------------------------------------+ | Land Side Main | The main chamber on the land side of the lock | +-----------------+----------------------------------------------------+ | Land Side Aux | An auxiliary chamber on the land side of the lock | +-----------------+----------------------------------------------------+ | River Side Main | The main chamber on the river side of the lock | +-----------------+----------------------------------------------------+ | River Side Aux | An auxiliary chamber on the river side of the lock | +-----------------+----------------------------------------------------+ Lockages ^^^^^^^^ Only values necessary to uniquely identify a lockage ("type", "lock_id", "date_time") are required for LockageCreated, LockageUpdated, and LockageDeleted messages. **LockageCreated Message Structure** +----------------+----------------------------------------------------------------------------------------+ | Message Type | Structure | +================+========================================================================================+ | LockageCreated | +------------+---------------+-------------------------------------------------------+ | | | | Value Type | Value Name | | | | | +============+===============+=======================================================+ | | | | String | "type" | "lockage_created" | | | | +------------+---------------+-------------------------------------------------------+ | | | | Object | "lock_id" | The lock identifier | | | | +------------+---------------+-------------------------------------------------------+ | | | | long | "date_time" | The date and time of the lockage in epoch millisecons | | | | +------------+---------------+-------------------------------------------------------+ | | | | int | "boat_count" | The number of boats locked through | | | | +------------+---------------+-------------------------------------------------------+ | | | | int | "barge_count" | The number of barges locked through | | | | +------------+---------------+-------------------------------------------------------+ | | | | double | "tonnage" | The tonnage of product locked through | | | | +------------+---------------+-------------------------------------------------------+ | | | | boolean | "upbound" | Whether traffic is headed upstream | | | | +------------+---------------+-------------------------------------------------------+ | | | | boolean | "emptying" | Whether lock is emptying | | | | +------------+---------------+-------------------------------------------------------+ | | | | String | "notes" | Lockage notes | | | | +------------+---------------+-------------------------------------------------------+ | +----------------+----------------------------------------------------------------------------------------+ **Example LockageCreated message** .. code-block:: json { "type": "lockage_created", "lock_id": { "office_id": "SWT", "name": "Green LD2-Lock" }, "date_time": 1788971820000, "boat_count": 1, "barge_count": 4, "tonnage": 10000.0, "upbound": true, "emptying": false, "notes": "Lockage completed successfully." } **LockageUpdated Message Structure** +----------------+----------------------------------------------------------------------------------------+ | Message Type | Structure | +================+========================================================================================+ | LockageUpdated | +------------+---------------+-------------------------------------------------------+ | | | | Value Type | Value Name | | | | | +============+===============+=======================================================+ | | | | String | "type" | "lockage_updated" | | | | +------------+---------------+-------------------------------------------------------+ | | | | Object | "lock_id" | The lock identifier | | | | +------------+---------------+-------------------------------------------------------+ | | | | long | "date_time" | The date and time of the lockage in epoch millisecons | | | | +------------+---------------+-------------------------------------------------------+ | | | | int | "boat_count" | The number of boats locked through | | | | +------------+---------------+-------------------------------------------------------+ | | | | int | "barge_count" | The number of barges locked through | | | | +------------+---------------+-------------------------------------------------------+ | | | | double | "tonnage" | The tonnage of product locked through | | | | +------------+---------------+-------------------------------------------------------+ | | | | boolean | "upbound" | Whether traffic is headed upstream | | | | +------------+---------------+-------------------------------------------------------+ | | | | boolean | "emptying" | Whether lock is emptying | | | | +------------+---------------+-------------------------------------------------------+ | | | | String | "notes" | Lockage notes | | | | +------------+---------------+-------------------------------------------------------+ | +----------------+----------------------------------------------------------------------------------------+ **Example LockageUpdated message** .. code-block:: json { "type": "lockage_updated", "lock_id": { "office_id": "SWT", "name": "Green LD2-Lock" }, "date_time": 1788971820000, "boat_count": 1, "barge_count": 4, "tonnage": 10000.0, "upbound": true, "emptying": false, "notes": "Lockage completed successfully." } **LockageDeleted Message Structure** +----------------+----------------------------------------------------------------------------------------+ | Message Type | Structure | +================+========================================================================================+ | LockageDeleted | +------------+---------------+-------------------------------------------------------+ | | | | Value Type | Value Name | | | | | +============+===============+=======================================================+ | | | | String | "type" | "lockage_deleted" | | | | +------------+---------------+-------------------------------------------------------+ | | | | Object | "lock_id" | The lock identifier | | | | +------------+---------------+-------------------------------------------------------+ | | | | long | "date_time" | The date and time of the lockage in epoch millisecons | | | | +------------+---------------+-------------------------------------------------------+ | +----------------+----------------------------------------------------------------------------------------+ **Example LockageDeleted message** .. code-block:: json { "type": "lockage_deleted", "lock_id": { "office_id": "SWT", "name": "Green LD2-Lock" }, "date_time": 1788971820000 } Decision Status =============== Status: request for comments References ==========