commit current maaike-wip for review

documentation/docs/practical-sessions/configuring-station-metadata.md

@@ -4,96 +4,132 @@ title: Configuring station metadata
 
 # Configuring station metadata
 
+!!! abstract
+
+    In this session you will practice configuring station metadata for your dataset.
+
 ## Introduction
 
 The wis2box has a collection of station metadata that is used to publish data on WIS2.
 Only data for stations configured in the wis2box station list will be published on your wis2box broker.
 The **WIGOS Station Identifier (WSI)** is used as the unique reference of the station which produced a specific set of observation data.
 
-## 
+## Create an authorization token for collections/stations
 
-Login to your student VM using SSH.
+To edit stations via the wis2box-webapp you will first to need create an authorization token.
 
-Ensure wis2box is running:
+Login to your student VM and ensure you are in the wis2box-1.0b5 directory:
 
 ```bash
-cd ~/wis2box-1.0b4
-python3 wis2box-ctl.py start
-python3 wis2box-ctl.py status
+cd ~/wis2box-1.0b5
 ```
 
-## Update the wis2box station list
-
-Pre-select a few stations in your country that you would consider for data publishing on WIS2. If you want to ingest your own data sample later during the WIS2 training, make sure to add the stations corresponding to your data.
+Then login into the wis2box-management container with the following command:
 
-Edit the file `~/wis2box-data/metadata/station/station_list.csv`:
+```bash
+python3 wis2box-ctl.py login
+```
 
-For each new station, add a row to the end of the file with the following values:
+Within the wis2box-container your can create an authorization token for a specific endpoint using the command: `wis2box auth add-token --path <my-endpoint>`.
 
-- `station_name`: the human readable name of the station
-- `wigos_station_identifier`: the WSI issued for the station
-- `traditional_station_identifier`: the traditional station identifier if a WSI does not exist
-- `facility_type`: the station/platform type (use **Land (fixed)** for land stations)
-- `latitude`: the latitude, in decimal degrees
-- `longitude`: the longitude, in decimal degrees
-- `elevation`: station elevation, in metres above sea level
-- `territory_name`: the human readable country name
-- `wmo_region`: the Roman numeral of your country based on WMO Regional Associations
+For example, to use a random automatically generated token for the `collections/stations` endpoint:
 
-!!! tip
-    Ensure that latitude and longitude values are correctly signed (for example, use the minus sign [`-`] for southern or western hemispheres.
+```{.copy}
+wis2box auth add-token --path collections/stations
+```	
 
-### Using data from OSCAR
+The output will look like this:
 
-It is recommended to use station information from the [WMO OSCAR/Surface](https://oscar.wmo.int/surface) system where available.
+```{.copy}
+Continue with token: 7ca20386a131f0de384e6ffa288eb1ae385364b3694e47e3b451598c82e899d1 [y/N]? y
+Token successfully created
+```
 
-The script `~/exercise-materials/create-station-list/oscar2wis2box.py` can be used to add stations to your station list if they are available in OSCAR/Surface.
+Or, if you want to define your own token for the `collections/stations` endpoint, you can use the following example:
 
-For example to add the stations with WIGOS-IDs=0-20000-0-78970, 0-20000-0-78969 and 0-20000-0-78962 to your `station_list.csv`, run the following commands: 
+```{.copy}
+wis2box auth add-token --path collections/stations MyCatIsCalledJessie!
+```
 
-```bash
-python3 ~/exercise-materials/station-list/oscar2wis2box.py 0-20000-0-78970 >> ~/wis2box-data/metadata/station/station_list.csv
-python3 ~/exercise-materials/station-list/oscar2wis2box.py 0-20000-0-78969 >> ~/wis2box-data/metadata/station/station_list.csv
-python3 ~/exercise-materials/station-list/oscar2wis2box.py 0-20000-0-78962 >> ~/wis2box-data/metadata/station/station_list.csv
+Output:
+
+```{.copy}
+Continue with token: MyCatIsCalledJessie! [y/N]? y
+Token successfully created
 ```
 
-### Review your station list
+!!! note "Exercise 1: Create an authorization token for collections/stations"
 
-Check the content of your station list from the command line as follows:
+    Please create an authorization token for the `collections/stations` endpoint using the instructions above.
 
-```bash
-cat ~/wis2box-data/metadata/station/station_list.csv
-```
+## add station metadata using the wis2box-webapp
 
-Or open the file in WinSCP.
+The wis2box-webapp provides a graphical user interface to edit station metadata.
 
-Keep adding lines to `station_list.csv` and ensure you have at least three stations defined.
+Open the wis2box-webapp in your browser: `http://<your-host>/wis2box-app`:
 
-## Publishing station metadata
+<img alt="wis2box-webapp" src="../../assets/img/wis2box-webapp.png" width="800">
 
-Login in to the **wis2box-management** container:
+And select stations:
 
-```bash
-cd ~/wis2box-1.0b4/
-python3 wis2box-ctl.py login
-```
+<img alt="wis2box-webapp-select-stations" src="../../assets/img/wis2box-webapp-select-stations.png" width="250">
 
-Run the following command to publish your station metadata:
+When you click add 'add new station' you are asked to provide the WIGOS-station-identifier for the station you want to add:
 
-```bash
-wis2box metadata station publish-collection
-```
+<img alt="wis2box-webapp-import-station-from-oscar" src="../../assets/img/wis2box-webapp-import-station-from-oscar.png" width="800">
+
+When you click search the station data is retrieved from OSCAR, please note that this can take a few seconds.
+
+Review the data returned by OSCAR and add missing data where required. Select a topic for the station and provide your authorization token for the `collections/stations` endpoint and click 'save' and the station will be saved:
+
+<img alt="wis2box-webapp-create-station-save" src="../../assets/img/wis2box-webapp-create-station-save.png" width="800">
+
+<img alt="wis2box-webapp-create-station-success" src="../../assets/img/wis2box-webapp-create-station-success.png" width="500">
+
+Go back to the station list and you will see the station you added:
+
+<img alt="wis2box-webapp-stations-with-one-station" src="../../assets/img/wis2box-webapp-stations-with-one-station.png" width="800">
+
+!!! note "Exercise 2: Add station metadata"
+
+    Please add three or more stations to the wis2box station metadata collection of your wis2box. 
+
+    Please use stations from your country if possible, especially if you brought your own data.
+
+    Otherwise, you can use the following WIGOS-station-identifiers for testing purposes:
+
+    - 0-20000-0-91334
+    - 0-20000-0-96323 (note missing station elevation in OSCAR)
+    - 0-20000-0-96749 (note missing station elevation in OSCAR)
+
+## Review your station metadata
+
+After saving your station metadata, you can review the content of your station metadata in the wis2box-webapp:
+
+You can verify the updated stations are available in the wis2box-api:
+
+<img alt="wis2box-api-stations" src="../../assets/img/wis2box-api-stations.png" width="800">
+
+You can also visit the wis2box-ui at `http://<your-host>` and select "explore" on your dataset and you will see the stations you added:
+
+<img alt="wis2box-ui-explore-stations" src="../../assets/img/wis2box-ui-explore-stations.png" width="800">
+
+!!! note "Exercise 3: Review your station metadata"
+
+    Verify the stations you added are associated to your dataset by visiting the wis2box-api and wis2box-ui endpoints for your host in your browser.
 
-Ensure that your new station metadata was published to the API, by navigating to `http://<your-host>.wis2.training/oapi/collections/stations/items`:
+You also have the option to view/update/delete the station in the wis2box-webapp. Note that you are required to provide your authorization token for the `collections/stations` endpoint to update/delete the station.
 
-<img alt="stationlist_from_oscar" src="../../assets/img/stationlist_from_oscar.png" width="800">
+!!! note "Exercise 4: Update/delete station metadata"
 
-Click on your station metadata record and inspect the content, noting how it relates to the content of the `station_list.csv` you have updated.
+    Please update/delete the station metadata for one of the stations you added using the wis2box-webapp.
 
 ## Conclusion
 
 !!! success "Congratulations!"
     In this practical session, you learned how to:
 
-    - update station metadata
-    - publish station metadata
+    - create an authorization token for the `collections/stations` endpoint
+    - add station metadata to the wis2box
+    - review stations associated to datasets in the wis2box-ui
+    - update/delete station metadata using the wis2box-webapp

documentation/docs/practical-sessions/wis2box-introduction.md

@@ -29,7 +29,7 @@ cd ~/wis2box-1.0b5
 
 ## wis2box-create-config
 
-The wis2box-create-config script is used to create the initial configuration of your wis2box. 
+The wis2box-create-config script can be used to create the initial configuration of your wis2box. 
 
 It will ask you a set of question to help setup your configuration.