Data Event Formats - Gates

Summary

CWMS needs a message structure to notify clients of gate-related events.

Opinions

Opinion 1

Summary: Use the structures described below for gate-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

Gate Groups

Only values necessary to uniquely identify a gate group (“type”, “group_id”), and values necessary to minimally describe a gate group (“project_id”) are required for GateGroupCreated and GateGroupUpdated messages.

GateGroupCreated Message Structure

Message Type

Structure

GateGroupCreated

Value Type Value Name Value String “type” “gate_group_created” Object “group_id” The gate group identifier String “project_id” The project identifier String “rating_spec_id” The rating specification identifier for gates in the group String “gate_type” The type of gates in the group (see table) boolean “can_be_submerged” Whether the gates in the group can be submerged boolean “always_submerged” Whether the gates in the group are alwasys submerged String “description” A description of the gates in the group

Example GateGroupCreated Message

{
  "type": "gate_group_created",
  "group_id": {
    "office_id": "SWT",
    "name": "Greenbrier Service Gates"
  },
  "project_id": "Greenbrier",
  "rating_spec_id": "Greenbrier.Opening-Service Gates,Elev;Flow.Linear.Production",
  "gate_type": "RADIAL",
  "can_be_submerged": false,
  "always_submerged": false,
  "description": "Service gates for Greenbrier Dam."
}

GateGroupUpdated Message Structure

Message Type

Structure

GateGroupUpdated

Value Type Value Name Value String “type” “gate_group_updated” Object “group_id” The gate group identifier String “project_id” The project identifier String “rating_spec_id” The rating specification identifier for gates in the group String “gate_type” The type of gates in the group (see table) boolean “can_be_submerged” Whether the gates in the group can be submerged boolean “always_submerged” Whether the gates in the group are alwasys submerged String “description” A description of the gates in the group

Example GateGroupUpdated Message

{
  "type": "gate_group_updated",
  "group_id": {
    "office_id": "SWT",
    "name": "Greenbrier Service Gates"
  },
  "project_id": "Greenbrier",
  "rating_spec_id": "Greenbrier.Opening-Service Gates,Elev;Flow.Linear.Production",
  "gate_type": "RADIAL",
  "can_be_submerged": false,
  "always_submerged": false,
  "description": "Service gates for Greenbrier Dam."
}

Only values necessary to uniquely identify a gate group (“type”, “group_id”) are required for GateGroupDeleted messages.

GateGroupDeleted Message Structure

Message Type	Structure
GateGroupDeleted	Value Type Value Name Value String “type” “gate_group_deleted” Object “group_id” The gate group identifier

Example GateGroupDeleted Message

{
  "type": "gate_group_deleted",
  "group_id": {
    "office_id": "SWT",
    "name": "Greenbrier Service Gates"
  }
}

Gate Types Table

Gate Type ID	Description
OTHER	Unknown or unspecified gate type
CLAMSHELL	Gate whose upper and lower halves separate to open
CREST	Gate that increases the crest elevation when raised
DRUM	Hollow cylindrical section shaped crest gate hinged at the axis that floats on an adjustable amount of water in a chamber
FUSE	Non-adjustable gate that is designed to fail (open) at a specific head
INFLATABLE	Crest gate that is inflated to form a weir
MITER	Doors hinged on opposite sides of a walled channel that meet in the center at an angle and are held closed by water pressure
NEEDLE	Flow-through gate that is controlled by placing various numbers of boards (needles) vertically in a support structure
RADIAL	Cylindrical section shaped gate hinged at the axis that passes water underneath when open
ROLLER	Cylindrical crest gate that rolls in cogged slots in piers at each end to control its height
STOPLOG	Crest gate whose height is controlled by varying the number of horizontal boards (logs) stacked between piers
VALVE	Small gate for passing small and precisely controlled amounts of water
VERTICAL SLIDE	Flat gate that slides vertically in tracks (with or without rollers) for control
WICKET	A group of small connected hinged gates (wickets) that overlap when closed and rotate together to open

Gates

Only values necessary to uniquely identify a gate (“type”, “gate_id”), and values necessary to minimally describe a gate (“group_id”) are required for GateCreated and GateUpdated messages.

GateCreated Message Structure

Message Type	Structure
GateCreated	Value Type Value Name Value String “type” “gate_created” Object “gate_id” The gate identifier String “group_id” The gate group identifier int “sort_order” The ordering position of the gate within the group

Example GateCreated Message

{
  "type": "gate_created",
  "gate_id": {
    "office_id": "SWT",
    "name": "Greenbrier-SG1"
  },
  "group_id": "Greenbrier Service Gates",
  "sort_order": 1
}

GateUpdated Message Structure

Message Type	Structure
GateUpdated	Value Type Value Name Value String “type” “gate_updated” Object “gate_id” The gate identifier String “group_id” The gate group identifier int “sort_order” The ordering position of the gate within the group

Example GateUpdated Message

{
  "type": "gate_updated",
  "gate_id": {
    "office_id": "SWT",
    "name": "Greenbrier-SG1"
  },
  "group_id": "Greenbrier Service Gates",
  "sort_order": 1
}

Only values necessary to uniquely identify a gate (“type”, “gate_id”) are required for GateDeleted messages.

GateDeleted Message Structure

Message Type	Structure
GateDeleted	Value Type Value Name Value String “type” “gate_deleted” Object “gate_id” The gate identifier

Example GateDeleted Message

{
  "type": "gate_deleted",
  "gate_id": {
    "office_id": "SWT",
    "name": "Greenbrier-SG1"
  }
}

Gate Changes

GateChangeCreated and GateChangeUpdated messages contain arrays of gate settings for each gate in the project. Each setting in the array has the following structure, with only “gate_id”, “opening”, and “opening_unit” values required.

Gate Setting Structure

Value Type	Value Name	Value
String	“gate_id”	The gate identifier (without office_id)
double	“opening”	The opening of the gate
String	“opening_unit”	The unit of the gate opening
double	“invert_elevation”	The invert elevation if the gate supports variable inverts
String	“elevation_unit”	The unit of the invert elevation

Only values necessary to uniquely identify a gate change (“type”, “project_id”, “date_time”) and values necessary to minimally describe a gate change (“pool_elevation”, “discharge_method”, and “release_reason”) are required for GateChangeCreated ang GateChangeUpdatedmessages.

GateChangeCreated Message Structure

Message Type

Structure

GateChangeCreated

Value Type Value Name Value String “type” “gate_change_created” Object “project_id” The project identifier long “date_time” The date and time of the gate change in epoch milliseconds double “pool_elevation” The headwater pool elevation at the time of the gate change double “tailwater_elevation” The tailwater elevation at the time of the gate change double “reference_elevation” An additional reference elevation if required to describe this gate change String “elevation_unit” The unit of elevation values double “old_total_discharge_override” Manual override of computed discharge just before the gate change double “new_total_discharge_override” Manual override of computed discharge just after the gate change String “discharge_unit” The unit of discharge values String “discharge_method” The method of determining the total discharge (see table) String “release_reason” The reason for releasing water from the project (see table) boolean “protected” Whether the gate change is protected from overwrites String “notes” Notes about the gate change Array “settings” Settings for each gate of the project

Example GateChangeCreated Message

{
  "type": "gate_change_created",
  "project_id": {
    "office_id": "SWT",
    "name": "Greenbrier"
  },
  "date_time": 1788971820000,
  "pool_elevation": 912.54,
  "tailwater_elevation": 860.4,
  "elevation_unit": "ft",
  "old_total_discharge_override": 4250.0,
  "new_total_discharge_override": 6525.0,
  "discharge_unit": "cfs",
  "discharge_method": "Calculated from gate opening-elev curves",
  "release_reason": "Flood control release",
  "protected": false,
  "notes": "Gate change for flood control.",
  "settings": [
    {
      "gate_id": "Greenbrier-SG1",
      "opening": 1.1,
      "opening_unit": "ft"
    },
    {
      "gate_id": "Greenbrier-SG2",
      "opening": 1.1,
      "opening_unit": "ft"
    },
    {
      "gate_id": "Greenbrier-LF",
      "opening": 0.0,
      "opening_unit": "%"
    }
  ]
}

GateChangeUpdated Message Structure

Message Type

Structure

GateChangeUpdated

Value Type Value Name Value String “type” “gate_change_updated” Object “project_id” The project identifier long “date_time” The date and time of the gate change in epoch milliseconds double “pool_elevation” The headwater pool elevation at the time of the gate change double “tailwater_elevation” The tailwater elevation at the time of the gate change double “reference_elevation” An additional reference elevation if required to describe this gate change String “elevation_unit” The unit of elevation values double “old_total_discharge_override” Manual override of computed discharge just before the gate change double “new_total_discharge_override” Manual override of computed discharge just after the gate change String “discharge_unit” The unit of discharge values String “discharge_method” The method of determining the total discharge (see table) String “release_reason” The reason for releasing water from the project (see table) boolean “protected” Whether the gate change is protected from overwrites String “notes” Notes about the gate change Array “settings” Settings for each gate of the project

Example GateChangeUpdated Message

{
  "type": "gate_change_updated",
  "project_id": {
    "office_id": "SWT",
    "name": "Greenbrier"
  },
  "date_time": 1788971820000,
  "pool_elevation": 912.54,
  "tailwater_elevation": 860.4,
  "elevation_unit": "ft",
  "old_total_discharge_override": 4250.0,
  "new_total_discharge_override": 6525.0,
  "discharge_unit": "cfs",
  "discharge_method": "Calculated from gate opening-elev curves",
  "release_reason": "Flood control release",
  "protected": false,
  "notes": "Gate change for flood control.",
  "settings": [
    {
      "gate_id": "Greenbrier-SG1",
      "opening": 1.1,
      "opening_unit": "ft"
    },
    {
      "gate_id": "Greenbrier-SG2",
      "opening": 1.1,
      "opening_unit": "ft"
    },
    {
      "gate_id": "Greenbrier-LF",
      "opening": 0.0,
      "opening_unit": "%"
    }
  ]
}

Only values necessary to uniquely identify a gate change (“type”, “project_id”, “date_time”) required for GateChangeDeleted messages.

GateChangeDeleted Message Structure

Message Type	Structure
GateChangeDeleted	Value Type Value Name Value String “type” “gate_change_deleted” Object “project_id” The project identifier long “date_time” The date and time of the gate change in epoch milliseconds

Example GateChangeDeleted Message

{
  "type": "gate_change_deleted",
  "project_id": {
    "office_id": "SWT",
    "name": "Greenbrier"
  },
  "date_time": 1788971820000
}

Discharge Methods Table

Discharge Methods
Calculated from gate opening-elev curves
Calculated from tailwater curve
Estimated by user
Adjusted by an automated method

Release Reasons Table

Release Reasons
Flood control release
Water supply release
Water quality release
Hydropower release
Other release

Decision Status

Status: request for comments

References