Add JSON Transformer example

Author: daniel-slaugh

apps/docs/docs/how-to/hydroserverpy/hydroserverpy-examples.md

@@ -1049,8 +1049,8 @@ data_connection = hs_api.dataconnections.get(uid='00000000-0000-0000-0000-000000
 
 #### Example: Create Data Connection
 
-```python
-# Create a new data connection in HydroServer
+```python
+# Create a new data connection in HydroServer
 new_data_connection = hs_api.dataconnections.create(
     name='Example Data Connection',
     data_connection_type='ETL',
@@ -1079,8 +1079,69 @@ new_data_connection = hs_api.dataconnections.create(
 )
 ```
 
+#### Example: Create Data Connection with JSON Transformer
+
+```python
+# Create a new HTTP + JSON data connection in HydroServer
+new_json_data_connection = hs_api.dataconnections.create(
+    name='USGS Instantaneous Values',
+    data_connection_type='ETL',
+    workspace='00000000-0000-0000-0000-000000000000',
+    extractor_type='HTTP',
+    extractor_settings={
+        'sourceUri': (
+            'https://waterservices.usgs.gov/nwis/iv/'
+            '?format=json'
+            '&sites={site_code}'
+            '&parameterCd={param_code}'
+            '&startDT={start_date}'
+            '&endDT={end_date}'
+        ),
+        'placeholderVariables': [
+            {'name': 'site_code', 'type': 'perTask'},
+            {'name': 'param_code', 'type': 'perTask'},
+            {
+                'name': 'start_date',
+                'type': 'runTime',
+                'runTimeValue': 'latestObservationTimestamp',
+                'timestamp': {
+                    'format': 'ISO8601',
+                    'timezoneMode': 'daylightSavings',
+                    'timezone': 'America/Denver',
+                },
+            },
+            {
+                'name': 'end_date',
+                'type': 'runTime',
+                'runTimeValue': 'jobExecutionTime',
+                'timestamp': {
+                    'format': 'ISO8601',
+                    'timezoneMode': 'daylightSavings',
+                    'timezone': 'America/Denver',
+                },
+            },
+        ],
+    },
+    transformer_type='JSON',
+    transformer_settings={
+        'JMESPath': 'value.timeSeries[].values[].value[]',
+        'timestamp': {
+            'key': 'dateTime',
+            'format': 'ISO8601',
+            'timezoneMode': 'embeddedOffset',
+        },
+    },
+    loader_type='HydroServer',
+    loader_settings={}
+)
+```
+
 `extractor_settings`, `transformer_settings`, and `loader_settings` should use the same nested JSON shape used by the Data Management app and TypeScript client. For example, HTTP extractors use `sourceUri` and `placeholderVariables` in camelCase.
 
+The USGS Instantaneous Values service accepts ISO-8601 datetimes and assumes site-local time when no offset is provided. This example uses a daylight-savings aware local timezone (`America/Denver`). If your sites are in a different timezone, replace that value with the appropriate IANA timezone for your tasks.
+
+The JSON transformer timestamp configuration also stays on `ISO8601` with `timezoneMode: 'embeddedOffset'` because USGS response `dateTime` values include their timezone offset. In HydroServer, ISO timestamps with embedded offsets are parsed directly; fixed-offset or daylight-savings transformer timezone settings are for sources whose timestamps do not already include timezone information.
+
 Each of the methods above will return one or more DataConnection objects. The examples below show the main properties and methods available to a DataConnection object.
 
 #### Example: Modify a Data Connection