Merge pull request #13 from Health-Informatics-UoN/Separate-wizard-docs

Moved wizard docs to separate section

Author: anwarfg

observablehq.config.js

@@ -22,15 +22,28 @@ export default {
       path: "/examples-in-five-safes-tes",
       open: false,
       pages: [
+        
         {name: "Submitting to Five Safes TES", path: "/examples-in-five-safes-tes/submitting-to-5s-tes"},
-        {name: "Submission layer wizards", path: "/examples-in-five-safes-tes/submission-layer-wizards"},
+        {name: "Running arbitrary containers", path: "/examples-in-five-safes-tes/Running arbitrary containers"},
         {name: "Collecting results", path: "/examples-in-five-safes-tes/collecting-results"},
-        {name: "Visualising OMOP metadata", path: "/examples-in-five-safes-tes/Bunny visualisations"},
-        {name: "Aggregating statistics", path: "/examples-in-five-safes-tes/aggregating-statistics"},
-        {name: "Contingency tables", path: "/examples-in-five-safes-tes/contingency-tables"},
         {name: "Five Safes TES messages", path: "/examples-in-five-safes-tes/5s-tes-messages"},
+
+      ]
+    },
+    {
+      name: "Wizard examples",
+      path: "/wizard-examples",
+      open: false,
+      pages: [
+        {name: "Making a submission through the Web application", path: "/wizard-examples/making-a-submission-through-the-web-application"},
+        {name: "Submission layer wizards", path: "/wizard-examples/submission-layer-wizards"},
+        {name: "Visualising OMOP metadata", path: "/wizard-examples/Bunny visualisations"},
+        {name: "Aggregating statistics", path: "/wizard-examples/aggregating-statistics"},
+        {name: "Contingency tables", path: "/wizard-examples/contingency-tables"},
+
       ]
     }
+
   ],
 
   // Content to add to the head of the page, e.g. for a favicon:

src/examples-in-five-safes-tes.md

@@ -27,7 +27,7 @@ The [Global Alliance for Genomics and Health](https://www.ga4gh.org/) (GA4GH) [T
 TES works by sending a standard format of HTTP requests to a server, which interprets these requests to run some task in its environment.
 <div class="tip">
 
-You do not need to know how to write this format to use 5s-TES, which has [tools](examples-in-five-safes-tes/submission-layer-wizards) to help you.
+You do not need to know how to write this format to use 5s-TES, which has [tools](/wizard-examples/submission-layer-wizards) to help you.
 
 </div>
 

src/examples-in-five-safes-tes/5s-tes-messages.md

@@ -8,12 +8,12 @@ title: Five Safes TES messages
 
 <div class="tip">
 
-The information included here is not essential, but can help you understand what's going under the hood of tools like [the wizards](examples-in-five-safes-tes/submission-layer-wizards)
+The information included here is not essential, but can help you understand what's going under the hood of tools like [the wizards](/wizard-examples/submission-layer-wizards)
 
 </div>
 
 The reference documentation for TES messages specifies the standard for [creating a task](https://ga4gh.github.io/task-execution-schemas/docs/#tag/TaskService/operation/CreateTask).
-5s-TES accepts this format, but some fields are treated differently because of how the [submission layer](examples-in-five-safes-tes#submission-layer) processes messages before they're sent to a TES engine.
+5s-TES accepts this format, but some fields are treated differently because of how the [submission layer](/examples-in-five-safes-tes#submission-layer) processes messages before they're sent to a TES engine.
 
 ## TES fields
 

src/examples-in-five-safes-tes/Running arbitrary containers.md

@@ -0,0 +1,36 @@
+---
+theme: air
+style: ../entrust-style.css
+title: Submission layer wizards
+---
+
+# Running arbitrary containers
+Five safes TES can run arbitrary containers, as long as the TRE can and will run them. This means that any analysis can be performed on a TRE. 
+
+In order to do this, you have to prepare a containerised version of the software you want to run. Typically, this may be a script such as python or R code, but can be any language or any tool. We do not currently support languages or tools which require external connections, such as to licence servers.
+
+To containerise a script or tool in this way, the software must be executable from the command line. Arguments can be passed in at runtime using the TES messages. The command line arguments will be used in the `command` section of the `executors` in the TES message. A script will have access to input data passed in through the TES message (through mounted filepaths specified in the inputs, if any) and output data by writing files to the output path specified in the outputs section of the TES message. We recommend using /inputs and /outputs where possible.
+
+The following is a list of environment variables which are used by Five Safes TES. This is primarily of interest as it outlines the names of the variables required for a connection string to the database, which is likely to be required to connect the container to the database. These variables will overwrite any that are passed through the TES message, as they are added by the submission layer.
+```
+"Any"
+"CATALOG"
+"SCHEMA"
+"myapi2"
+"myapikey"
+"postgresDatabase"
+"postgresPassword"
+"postgresPort"
+"postgresSchema"
+"postgresServer"
+"postgresUsername"
+"submissionId"
+"test"
+"trinoPassword"
+"trinoURL"
+"trinoUsername"
+```
+
+Once your script or tool is ready, it must be built into a [docker container.](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/) The container also should be published so it can be accessed by the TRE. A simple way to publish to an accessible location is using [github.](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry?utm_source=chatgpt.com)
+
+TREs can then approve and copy the container locally, to be usable on request (through a TES message). This means you can then submit a TES message to run the new image on the TRE.

src/examples-in-five-safes-tes/collecting-results.md

@@ -4,7 +4,7 @@ title: Collecting results
 ---
 # Collecting results
 
-These instructions assume you have [submitted a task](submitting-to-5s-tes) using one of [the wizards](submission-layer-wizards).
+These instructions assume you have [submitted a task](submitting-to-5s-tes).
 
 When you have submitted a task, you have to wait for your results to be ready to collect.
 If you navigate back to the view of the Submissions to a project from which you can start a wizard, you can view past submissions.

src/examples-in-five-safes-tes/submitting-to-5s-tes.md

@@ -67,19 +67,3 @@ The time and date at which your current token expires are shown above the token
 </div>
 
 
-## Making a submission through the Web application
-As each submission is associated with a project, you make your submissions in the web application by first navigating to the projects view.
-![A screenshot of the web application, highlighting the link to the projects view](./project-in-ribbon.png)
-In the projects view, you can then select a project you are assigned to.
-
-When you are in the project, you can select the Submissions view.
-![A screenshot of a project, highlighting the link to the submissions](./view-of-project.png)
-
-In the Submissions view, you will be shown a button to make a new submission.
-Clicking the Create Submission button will give you the options
-
-- TES wizard
-- GraphQL TES wizard
-![A screenshot of the Submissions view, hightlighting the button used for the wizards](./submissions-view.png)
-
-[The TES wizard](submission-layer-wizards) can help you make a submission

src/wizard-examples.md

@@ -0,0 +1,11 @@
+---
+theme: air
+style: entrust-style.css
+title: Wizard examples
+---
+
+# Wizard examples
+
+These pages walk through the submission-layer wizards in the Five Safes TES web application: choosing a wizard, filling in TES details, and submitting a task.
+
+Use the links in the sidebar for step-by-step topics, or start with [Submission layer wizards](wizard-examples/submission-layer-wizards).

…n-five-safes-tes/Bunny visualisations.md …/wizard-examples/Bunny visualisations.mdsrc/examples-in-five-safes-tes/Bunny visualisations.md renamed to src/wizard-examples/Bunny visualisations.md src/examples-in-five-safes-tes/Bunny visualisations.md renamed to src/wizard-examples/Bunny visualisations.md

@@ -7,7 +7,7 @@ title: Visualising Bunny Outputs
 This tutorial can be run as a Jupyter notebook in the [5s-TES notebooks repository](https://github.com/Health-Informatics-UoN/5s-TES-notebooks/tree/main/OMOP-metadata), which also contains the utilities used to visualise OMOP metadata.
 
 There are two examples of outputs from a Bunny distribution query included in the test data.
-This kind of data can be obtained from Five Safes TES (5STES) by submitting a TES message, which can be created by using the [custom image wizard](submission-layer-wizards#custom-image):
+This kind of data can be obtained from Five Safes TES (5STES) by submitting a TES message, which can be created by using the [custom image wizard](/wizard-examples/submission-layer-wizards#custom-image):
 ![Screenshot of the custom image wizard running a bunny query](./bunny-custom-image-wizard.png)
 
 The settings need to be:

…five-safes-tes/aggregating-statistics.md …izard-examples/aggregating-statistics.mdsrc/examples-in-five-safes-tes/aggregating-statistics.md renamed to src/wizard-examples/aggregating-statistics.md src/examples-in-five-safes-tes/aggregating-statistics.md renamed to src/wizard-examples/aggregating-statistics.md

@@ -12,7 +12,7 @@ The outputs from TES tasks can be easily used to calculate basic statistics.
    This example will use summary statistics from a dataset in the OMOP common data model.
 There is a container which, given a SQL query that filters an OMOP table by your criteria, will calculate the necessary summary statistics for your final analysis.
 
-This example data was collected using the [Custom Image wizard](submission-layer-wizards#custom-image) in the submission layer with these settings changed from default:
+This example data was collected using the [Custom Image wizard](/wizard-examples/submission-layer-wizards#custom-image) in the submission layer with these settings changed from default:
 
 | Field   | value                                                                          |
 | ------- | ------------------------------------------------------------------------------ |