Upload wagon configuration via JSON documentation.

docs/hyperloop/userdocumentation.md

@@ -7,7 +7,7 @@
 
 When opening a page in Hyperloop which has not been visited before, a guided tour will explain key concepts. These tours provide an interactive learning experience for Hyperloop, easily activated with a single click. They are ideal for beginners and for refreshing knowledge.
 
 Where appropriate, when one tour ends, the next will begin to explain the next section of Hyperloop. Tours can be exited at any time. Once closed, they will not automatically begin on future page visits. 
 
 <div align="center">
 <img src="../images/JoyrideWelcome.png" width="35%">
@@ -85,7 +85,7 @@
 <div align="center">
 <img src="../images/wagonShortcuts.png" width="80%">
 </div>
 
 ## <a name="wagon-settings"></a> Wagon Settings
 
 * <a name="wagonsettings"></a>In _Wagon settings_ you can modify the wagon name, work flow name, and select wagon's dependencies. The dependencies offered are wagons from the same _Analysis_ or from [_Service wagons_](#servicewagons).
@@ -93,7 +93,7 @@
 <div align="center">
 <img src="../images/wagonSettings.png" width="70%">
 </div>
 
 ## <a name="wagon-configuration"></a> Wagon Configuration
 
 * <a name="wagonconfiguration"></a>In _Configuration_ the wagon configuration corresponding to the workflow will be available in the _Base_. The configuration is divided per _Task_, hence if you need to add a new parameter, you will need add it in the following order: task, parameter and value.
@@ -120,16 +120,57 @@
 
 * In order to update the base and subwagon configuration with the latest version of the workflow, click on the button `↻ sync` in _Configuration_. By synchronizing the configuration, the parameters which no longer belong to the workflow will be removed, and the values of the wagon's _Base_ will be updated as well if they have not been modified by the user.
 
+### <a name="upload-wagon-json"></a> Upload Wagon Configuration via JSON
+
+* <a name="uploadwagonjson"></a> The wagon configuration may be adjusted via JSON file. Any values in the wagon will be adjusted to the values in the JSON file. 
+
+<div align="center">
+<img src="../images/updateViaJSONButton.png" width="30%">
+</div>
+
+* The required format for Hyperloop to ingest the JSON is the exact format given when downloading the configuration JSON file from Hyperloop (from the download button above). This download includes workflows from dependencies. When uploading, it is not necessary to remove dependencies - any workflows not directly from the wagon will be ignored during the upload.
+
+<div align="center">
+<img src="../images/updateViaJSONPageOne.png" width="50%">
+</div>
+
+* Only configurables and subwagons which already exist in the wagon may be edited - any new subwagons or configurables in the JSON will be ignored. To add new subwagons, first add them to the existing wagon. When a file is chosen, each changed value is shown in the 'overview'. All values in 'base' are listed first, with subwagons listed below. In the example below, there are two subwagons, 'Pos' and 'Neg'. Hovering over any value will display the change in a tooltip.
+
+<div align="center">
+<img src="../images/updateViaJSONOverview.png" width="40%">
+</div>
+
+* There is validation to check for invalid values. It also ensures that there are no identical subwagons. 
+
+<div align="center">
+<img src="../images/updateViaJSONValidation.png" width="40%">
+</div>
+
+* A full diff between the current and uploaded configuration is also available. Every difference between the current and uploaded configuration is shown.
+
+<div align="center">
+<img src="../images/updateViaJSONDiff.png" width="40%">
+</div>
+
+* Once 'Apply Changes' is pressed, any altered values will be highlighted in yellow. No changes are saved until the 'save' button is pressed, so it is possible to apply the changes to view them without losing the current configuration.
+
+<div align="center">
+<img src="../images/updateViaJSONHighlight.png" width="70%">
+</div>
+
+
+
+
 ## <a name="wagon-derived-data"></a> Derived data 
 
 * <a name="wagonderived"></a>In _Derived Data_ the tables which are produced by the task are displayed. If activated, these are saved to the output if the train is run as a derived data production. The produced derived data can be made available by the operators and serve as input for subsequent trains. 
 
 ### <a name="deriveddatatypes"></a> Derived data types
 * There are three types of derived data specifications:
   * Standard derived data (marked with 🗂️)- if the wagon is used in a train, this will produce derived data to be used for further analysis. The results will not be merged across runs and can be used as input for future train runs. Note that standard derived data trains do not submit automatically and may need additional approval. If in doubt, please seek advise before enabling derived data tables in your wagon configuration.
   * Slim derived data (marked with green bordered 🗂️) - similarly to the standard derived data case, if used in a train, this will produce derived data to be used for further analysis. This is reserved for derived data of small output size. The results will be merged across runs and are not available to use in future train runs. The data will be automatically deleted after a preset period of time. You can mark a wagon for running as slim derived data by checking `Ready for slim derived data`.
   * Linked derived data (marked with red bordered 🗂️) - linked derived data trains will also produce derived data to be used for further analysis. Linked derived data has access to the parent AO2D - this is not the case for other derived data types. Like standard derived data, results are not merged across runs.
 
 * For wagons set as ready for slim derived data, two more fields need to be correctly set:
   * Max DF size - This sets the maximal dataframe size in the merging step. Has to be 0 for not-self contained derived data (which need parent file access).
   * Max derived file size - Sets the size limit for the output file size of the derived data file. This is an expert parameter which usually does not have to be changed. Only change this value if the processing in subsequent trains takes so long that the jobs fail. If set to 0 a good value will be automatically determined.
@@ -144,7 +185,7 @@
 <img src="../images/derivedDataEx.png" width="70%">
 </div>
 
 ## <a name="wagon-test-statistics"></a> Test Statistics 
 
 * <a name="wagonteststatistics"></a>_Test Statistics_ contains three graphs that display different metrics following the tests this wagon was part of. The first graph plots the _PSS Memory_ corresponding to each test run. The second one diplays the _CPU Time_, _Wall time_ and _Throughput_ along the test runs for this wagon. Finally, the third graph shows the _Output size_ at each test run.