This tutorial will teach you how to migrate your existing HEC-RTS Extract Lists from a local Oracle database to a CWMS Data API (CDA) connection. This migration is required as all offices transition to cloud environments utilizing CDA for national database connectivity.

Prerequisites

Before beginning the migration, ensure you have a configured login for your target CDA connection. If you need to set up a new connection, please refer to the Setting up a CDA Extract Group documentation before proceeding.

Step 1: Create a Copy of the Extract XML File

  1. Close HEC-RTS.
  2. Open Windows Explorer and navigate to the extract folder inside your watershed directory (<watershed name>/shared/extract).
  3. Locate the XML file for the Extract List you need to update (named [extract list].xml) and create a copy of it.
  4. Rename the copy to CDA_[original name].xml.
  5. Repeat this process for any additional Extract Lists requiring migration.

Step 2: Update the Data Source (Datastore)

For Extract Lists, the Datastore defines where HEC-RTS pulls its data. This configuration sits at the top of the XML file.

The image below is an example of what the file should look like before any edits.

  1. Open the newly created CDA_[original_name].xml file in a text editor (Notepad++ is highly recommended).
  2. Near the top of the file, locate the <datastore> block.
  3. Change the opening and closing tags from Oracle to RADAR:
    1. Replace <oracle id="Oracle"> with <radar id="RADAR">. 
    2. Replace </oracle> with </radar>.
  4. Delete the old connection lines within that block and replace them with your new authentication source string:
    1. <cwms_authentication_source version="v1" cwms_source_type="cwms_radar" cwms_radar_url="https://cwms-data-test.cwbi.us/cwms-data/" office_id="[YOUR_OFFICE_ID]">[YOUR_OFFICE_ID]_CDA</cwms_authentication_source>
    2. Replace [YOUR_OFFICE_ID] with your specific office code, e.g., MVS.

The image below is an example of what the file should look like after you complete the necessary edits.

Step 3: Rename the Extract List

Renaming the list ensures users can easily differentiate between Oracle and CDA sources inside the watershed.

 The image below is an example of what the file should look like before any edits.

  1. Locate the <ts-dataexchange-set> tags further down in the file.
  2. Update the id attribute (id="[original_name]") to include the CDA prefix (e.g., id="CDA_[original_name]").

  3. Update the secondary id attribute (id="[original_name]1") to also include the CDA prefix (e.g., id="CDA_[original_name]1").

    1. This name must have the 1 appended to the end of the text.
  4. Update the datastore references within these same lines to point to RADAR. 
    1. Change the <datastore-ref> from id="Oracle" to id="RADAR" office-id="[YOUR_OFFICE_ID]".
    2. In this example, the Office ID used is MVS.

The image below is an example of what the file should look like after you complete the necessary edits.

Step 4: Update Timeseries Datastore IDs

You now need to change the references for each timeseries listed in the Extract XML file.

Do not use global Find and Replace for this step. Update each entry individually to avoid breaking unintended lines of code.

The image below is an example of what the file should look like before any edits.

  1. Scroll down to the <cwms-timeseries> mappings in the file.
    1. In this example, it starts on line 24 (the Roselle-St Francis timeseries).
  2. Change datastore-id="Oracle" to datastore-id="RADAR".
  3. Repeat this adjustment manually for every remaining timeseries entry in the file.
  4. Save and close the file.

The image below is an example of what the file should look like after you complete the necessary edits.

Step 5: Verify Changes to the Extract List

  1. Launch HEC-RTS and open your watershed.
  2. Switch to the Setup tab.
  3. From the Models menu, select Edit Extract.
  4. Select your newly created CDA Extract List.
  5. Verify that the data source successfully displays as CDA.
  6. Create a test Forecast and run the extract to ensure data is pulling correctly without errors.

Final Steps

Repeat Steps 2 through 5 individually for each new XML file you created to ensure all data sources and timeseries are properly mapped and tested.