Add a Description field to Connections

[amabdallah]

Describe the feature you'd like and what it will do

We need a generic Description field added to Connections where we can document info about the connection and its parameters and why they're set up this way. Each task should inherit the description or at least have a URL pointing back to the description of its parent connection.

Why is this feature important?

1. So all of our staff have access to the same info (one source of truth)
2. So staff can add a new task knowing what the parameters mean
3. Add already public contact info about the Connection.

Use case, a staff wants to add a new task to the RISE Connection to scrape data for a new reservoir. They need to know what location_id and parameter_id mean and where to get them from. Ideally, they can look up the Connection description and learn about its parameters, what they mean, and where to get them from (e.g.,
Parameter id for Lake/Reservoir Storage=3 (refer to /rise/api/parameter)
For more info reach out to
Open Water Data Coordinator
Allison Odell
720-672-5107
aodell@usbr.gov

Is your feature request related to a problem? Please describe.

No response

Any additional comments?

No response

[amabdallah]

@kjlippold thank you so much for the super quick deployment of this feature. Could you triple the maximum characters allowed to 12,000? I tried to post this but ran into the Maximum 3000 characters allowed limit. I know this is probably is a lot of text to include here but it's super handy for us. Our custom tool could improve its display and add "view more" but for now, let us store it as-is.

---

Reclamation Information Sharing Environment (RISE) Connection Description

This connection is configured to retrieve time-series data from the Reclamation Information Sharing Environment (RISE) Application Programming Interface (API) for Bureau of Reclamation reservoirs.

RISE API Documentation:
https://data.usbr.gov/rise/api

The connection relies on two API parameters that uniquely identify each dataset:

1. location_id – Identifies the reservoir or monitoring location associated with the dataset. RISE publishes a feature layer containing all point locations associated with datasets available through the platform.

   ArcGIS Feature Layer:
   https://www.arcgis.com/home/item.html?id=0c77cc20d1f645cb985c98b06a5dbc39#overview

2. parameter_id – Identifies the physical or modeled characteristic being measured. RISE parameters describe analytes, measurements, or modeled quantities and are uniquely defined by the combination of Parameter Name, Group, Units, Timestep, and Transformation.

   RISE Parameter API:
   https://data.usbr.gov/rise/api/parameter?page=1&itemsPerPage=25

Dataset Identification

The RISE dashboard and many API examples identify datasets using a single itemId. For example, the following dataset:

Hyrum Reservoir and Dam – Observed Daily Instantaneous Lake/Reservoir Storage (af)

is identified as:

itemId = 439

Example API request:

https://data.usbr.gov/rise/api/result?itemsPerPage=2000&order%5BdateTime%5D=ASC&itemId=439&dateTime%5Bafter%5D=20260720&dateTime%5Bstrictly_before%5D=20260728

The Utah Division of Water Rights implementation instead identifies datasets using the combination of location_id and parameter_id. This approach is consistent with the former Reclamation data source:

https://www.usbr.gov/uc/water/nws_data_file/nwsdata.dat

That source also identified datasets using a site name and parameter name, for example:

"HYRUM"|"pool elevation"
"STATELINE"|"inflow"

This approach is preferred because the two identifiers represent the fundamental components of every observation:

• where the measurement was collected (location_id), and
• what was measured (parameter_id).

Unlike itemId, which is simply a dataset identifier, the location_id + parameter_id combination is semantically meaningful, more transparent, and easier to validate against RISE metadata. It also aligns naturally with the Division's data model and ETL architecture, where locations and parameters are managed independently.

This approach improves maintainability, simplifies troubleshooting, and makes it easier to verify that each configured data stream is retrieving the intended measurement.

For the same dataset:

Hyrum Reservoir and Dam – Observed Daily Instantaneous Lake/Reservoir Storage (af)

the connection uses:

• location_id = 372
• parameter_id = 3

Example API request:

https://data.usbr.gov/rise/api/result?page=1&itemsPerPage=5000&locationId=372&parameterId=3&dateTime%5Bafter%5D=2026-07-24T07:00:00+00:00&dateTime%5Bbefore%5D=2026-07-27T08:31:07.409277+00:00&catalogItem.isModeled=false

Parameters Currently Used

Parameter 2 – Lake/Reservoir Elevation

• Description: Instantaneous daily lake or reservoir water-surface elevation measured in feet (ft). Elevation is typically referenced to mean sea level (MSL) or another specified vertical datum. One observation is reported per day.
• Timestep: Daily
• Transformation: Instant
• Units: ft

Parameter 3 – Lake/Reservoir Storage

• Description: Instantaneous daily lake or reservoir storage volume measured in acre-feet (af). Storage represents the total volume of water contained within the reservoir at the time of observation. One observation is reported per day.
• Timestep: Daily
• Transformation: Instant
• Units: af

Parameter 12 – Lake/Reservoir Inflow

• Description: Average daily inflow to a lake or reservoir measured in cubic feet per second (cfs). The value represents the average rate of water entering the reservoir from all contributing sources during the day.
• Timestep: Daily
• Transformation: Average
• Units: cfs

Parameter 18 – Lake/Reservoir Release – Total

• Description: Average daily total release from a lake or reservoir measured in cubic feet per second (cfs). Total release is the combined flow from all release pathways, including the powerplant, outlet works, bypass, spillway, and other controlled-release structures.
• Timestep: Daily
• Transformation: Average
• Units: cfs

Adding a New RISE Retrieval Task

To add a new RISE data-retrieval task, first select the appropriate parameter_id based on the measurement type, such as elevation, storage, inflow, or total release. Next, use the RISE Utah Stations Attributes Table to locate the reservoir or monitoring site and obtain its corresponding location_id.

Configure the task using the selected parameter_id together with the identified location_id. Before enabling the task, verify that the resulting API request returns the expected location, parameter, units, timestep, and transformation.

RISE Utah Stations Attributes Table:
https://docs.google.com/spreadsheets/d/1Hn4sstdbi9I2fLmmszHpuRq1utqVcim1KhZJGbetxWc/edit?usp=sharing

Additional Information

For additional information, contact:

Allison Odell
Open Water Data Coordinator
Bureau of Reclamation
720-672-5107
aodell@usbr.gov

[horsburgh]

@kjlippold and @amabdallah - this is a lot of text. And it has formatting. Would this be better done as a markdown file or something?

[amabdallah]

Instead, let's then this URL that points to our documentation page.
https://utah-division-of-water-rights.gitbook.io/dataservices/a5qL93uhySSoRk3cklbQ/measurement-data/data-providers/rise-reclamation

[kjlippold]

I think we could add an optional link field in addition to the description to support markdown or other extended information that doesn't fit in the description.