Documentation: Sample linking in download/upload feature & SOP

_data/sidebars/user_guide.yml

@@ -47,7 +47,7 @@ subitems:
         subitems:
         - title: Creating a Project
           url: /help/user-guide/create-a-project
-        - title: Administer project members
+        - title: Administer Project members
           url: /help/user-guide/administer-project-members
         - title: Joining a Project
           url: /help/user-guide/join-a-project
@@ -68,26 +68,30 @@ subitems:
         url: /help/user-guide/isa-overview
       - title: Generating the ISA structure
         url: /help/user-guide/generating-the-isa-structure
-      - title: ISA-JSON compliant experiments
+      - title: ISA-JSON compliant Experiments
         url: /help/user-guide/isa-json-compliant-experiment
     - title: Investigations
       subitems:
-      - title: Creating an ISA-JSON compliant investigation
+      - title: Creating an ISA-JSON compliant Investigation
         url: /help/user-guide/investigations
       - title: Export experiments as ISA-JSON
         url: /help/user-guide/exporting-experiments-as-isajson
     - title: Studies
       subitems:
-      - title: Creating an ISA-JSON compliant study
+      - title: Creating an ISA-JSON compliant Study
         url: /help/user-guide/studies
-      - title: Editing an ISA-JSON compliant study
+      - title: Editing an ISA-JSON compliant Study
         url: /help/user-guide/edit-isa-studies
+      - title: Creating Samples in a ISA-JSON compliant Study
+        url: /help/user-guide/create-sample-isajson-compliant#create-study-sources
     - title: Assays
       subitems:
-      - title: Creating an ISA-JSON compliant assay
+      - title: Creating an ISA-JSON compliant Assay
         url: /help/user-guide/assays
-      - title: Editing an ISA-JSON compliant assay
+      - title: Editing an ISA-JSON compliant Assay
         url: /help/user-guide/edit-isa-assays
+      - title: Creating Samples in a ISA-JSON compliant Assay
+        url: /help/user-guide/create-sample-isajson-compliant#create-assay-samples
     - title: Experiment Sample Templates
       subitems:
       - title: Creating Experiment Sample Templates
@@ -196,7 +200,7 @@ subitems:
     title: User guide for API
     description: Introduction to the API.
     subitems:
-    - title: API Introduction
+    - title: API introduction
       url: /help/user-guide/api
   -
     hr: true

help/user-guide/adding-admin-items.md

@@ -1,5 +1,5 @@
 ---
-title: Admin created items
+title: Adding admin items
 ---
 
 These are items that cannot be created by a general user, but can be created by a SEEK administrator, [Project Administrator](roles#project-administrator), or [Programme Administrator](roles.html#programme-administrator)

help/user-guide/administer-project-members.md

@@ -1,11 +1,11 @@
 ---
-title: Administer project members
+title: Administer Project members
 ---
 
 
 These are actions that can be carried out by a SEEK administrator, [Project Administrator](roles#project-administrator), or [Programme Administrator](roles.html#programme-administrator)
 
-## Add and remove people from a project
+## Add and remove people from a Project
 
 Part of administering a project will involve adding to or removing people from it. You can do this if you are a [Project Administrator](roles#project-administrator) or you are
 a [Programme Administrator](roles.html#programme-administrator) of a Programme that Project falls under.
@@ -18,13 +18,13 @@ institution in one action.
 Don't forget to confirm the changes with the Confirm button when finished.
 
 
-## Assign people to project roles
+## Assign people to Project roles
 
 As a [Project Administrator](roles.html#project-administrator) (or SEEK system administrator) you can assign people to roles. From the Administer menu on the project page select "Administer project member roles". To add to each role start to type the name of the person. You can remove by clicking the 'x' next to their name.
 
 The people must be first have been [added to the project](administer-project-members.html#add-and-remove-people-from-a-project) before they can be assigned to a role.
 
 
-## Flag when a person becomes inactive in a project
+## Flag when a person becomes inactive in a Project
 
 *Coming soon*

help/user-guide/api.md

@@ -1,5 +1,5 @@
 ---
-title: API Introduction
+title: API introduction
 ---
 
 {{ site.seek_instance.name | default: "FAIRDOM-SEEK" }} includes a [JSON](https://www.json.org/) Application

help/user-guide/assays.md

@@ -17,8 +17,8 @@ In the context of an ISA-JSON compliant experiment, we use the terms ISA Investi
 * Select an Assay Stream, then click on "Design Assay" button at the top right corner of the page.
 * Fill out the provided form as explained below.
 
-### 2.1 Link the sampling Protocol
-Select Protocols already registered in the platform that describe the used method or procedure (SOP) applied to the Assay. See how to [create an SOP](sops) in SEEK.
+### 2.1 Link the Protocol
+Select Protocols already registered in the platform that describe the used method or procedure (SOP) applied to the Assay. See how to [create an SOP](sops) in SEEK. You can later change the SOP when editing the Assay.
 
 ### 2.2 Design a Samples table for Assay
 
@@ -65,7 +65,7 @@ Upon creation, the newly designed ISA Assay will appear in the tree view on the
 ## 3. Adding samples to ISA Assay
 Follow the link to know how to [create samples in ISA-JSON compliant experiments](create-sample-isajson-compliant), including [Assay Samples](create-sample-isajson-compliant#create-assay-samples).
 
-## 4. Managing assays in an assay stream
+## 4. Managing assays in an Assay Stream
 When editing or deleting an assay from an assay stream, different conditions apply depending on whether the assay has associated samples.
 
 ### 4.1 Deleting an Assay

help/user-guide/create-a-project.md

@@ -1,5 +1,5 @@
 ---
-title: Creating a project
+title: Creating a Project
 ---
 
 ## What is a Project

help/user-guide/create-sample-isajson-compliant.md

@@ -1,8 +1,11 @@
 ---
-title: Working with Samples in ISA-JSON compliant Experiments
+title: Samples in ISA-JSON compliant Experiments
 ---
 
 ## Types of samples in ISA-JSON compliant Experiments
+The ISA metadata framework requires the description (metadata) of different types of samples, namely Study Sources, Study Samples and Assay Samples. This description is based on customisable [Experiment Sample Templates](isa-json-compliant-experiment) and includes the linking of applied [Protocols](SOPs). Follow the link for an overview about [ISA-JSON compliant experiments](isa-json-compliant-experiment).
+
+In the context of an ISA-JSON compliant experiment, we use the terms [ISA Investigation](investigations), [ISA Study](studies), and [ISA Assay](assays) when referring to Investigation, Study, and Assay, respectively.
 
 Study Source(s)
 * Study Sources must be created within an ISA Study, using an Experiment Sample Template level "Study Source".
@@ -21,50 +24,58 @@ Material output assay sample(s)
     * Assay samples from one preceding Assay, in the same Assay Stream.
 
 Data file output assay sample(s)
-Same as for material output assay sample(s), but for assays specifically designed to produce data files.
+* Same as for material output assay sample(s), but for assays specifically designed to produce data files.
 
 
 ## Creating samples in ISA-JSON compliant Experiments
 
 ### Create Study Sources
-From Study design tab, Sources can be created in three ways.
+From Study design tab in [experiment view](viewing-project-in-single-page), Sources can be created in two ways.
 
 #### Via the Add row button.
 1. Select the Add row button at the bottom of the page. One row corresponds to one Source.
 2. Make sure to fill in all the mandatory columns and then select Save.
-* Note that the light blue cells will define the name of each Source.
+* Note that the light blue cells will define the name of each Source and should ideally be unique.
 3. Click on Save. For each row that gets saved, a single Study Source is created.
 
-#### Via the Paste From Clipboard button
-1. Use one of the following buttons to export the table and save it locally: "Export to CSV", "Copy to Clipboard" or "Batch download to Excel".
-2. Fill in the table offline and copy the content. Ensure to select and copy all columns except for "id" and "uuid".
-3. Use the "Paste From Clipboard" button to fill in the table.
-4. Select Save. For each row that gets saved, a single Source is created.
-
 #### Via upload of the downloaded dynamic table
+In the Source table window in experiment view:
 1. Click on "Batch download to Excel".
-2. Open the downloaded excel file, fill in the table offline and save it locally.
-3. Navigate to the same Sources table from the Study design tab, click on "Choose File" button at the bottom of the page, select the saved excel file and click "Upload".
+2. Open the downloaded Excel file, fill in the table offline and save it locally.
+3. Navigate to the same Sources table from the Study design tab, click on "Choose File" button at the bottom of the page, select the saved Excel file and click "Upload".
 4. Verify and confirm the upload via the pop-up window, then click "Save".
+* If the file contains 100 rows or fewer, saving happens immediately. 
+* If the file contains more than 100 rows, saving runs as a background job. When processing finishes, you will receive an email notification, and the Sources will be available in the table.
 
 ![create study sources]({{ "/images/user-guide/isajson-compliance/create_samples_isastudy_source_4.png" | relative_url }}){:.screenshot}
 
 ### Create Study Samples
-In the Study design tab, Samples can be created in three ways, similar to Sources (see above). The only difference is the mandatory column "Input" in the Samples table, which must be filled with valid and existing Sources from the same Study.
+In the Study design tab in [experiment view](viewing-project-in-single-page), Samples can be created in two ways, similar to Sources (see above). The only difference is the mandatory column "Input" in the Samples table, which must be filled with valid, existing Sources from the same Study. This requirement exists because the ISA model enforces sample lineage: every Study Sample must be derived from at least one Source to preserve traceability within the experimental design.
 
 #### Via the Add row button.
-Select the input Source(s) for the Sample your are creating in the "Input" column.
-
-#### Via the Paste From Clipboard button
-Ensure to select and copy all columns except for "Input", "id" and "uuid". "Input" cannot be pasted from clipboard, it must be added manually.
+Select the input Source(s) for the Sample you are creating in the "Input" column. Fill in the other metadata fields. Click on Save. For each row that gets saved, a single Study Sample is created. 
+Note that it is possible to define a one-to-many relation (a single Source can be used in different Study Samples) or a many-to-one relation (multiple Sources can be the input for a single Study Sample). 
 
 ![create study samples 5]({{ "/images/user-guide/isajson-compliance/create_samples_isastudy_samples_5.png" | relative_url }}){:.screenshot}
 
 #### Via upload of the downloaded dynamic table
-Values for the mandatory column "Input" in the Samples table can be added in batch via spreadsheet upload.
-
-Open the downloaded excel file and fill in the "Input" column by providing the *Source id* and the *Source title* in the following format. id: numeric id assigned by the platform to each Source; title: Source Name given by the user to each Source.
-
+In the Samples table window in experiment view:
+1. Click Batch download to Excel to export the table.
+2. Open the downloaded Excel file and fill in the rows offline. Values for the mandatory Input column in the Samples table can be added in batch.
+3. Navigate to the same Study Samples table from the Study design tab, click on "Choose File" button at the bottom of the page, select the saved Excel file and click "Upload".
+4. Verify and confirm the upload via the pop-up window, then click "Save".
+* If the file contains 100 rows or fewer, saving happens immediately. 
+* If the file contains more than 100 rows, saving runs as a background job. When processing finishes, you will receive an email notification, and the Sources will be available in the table.
+
+Linking Sources to a Study Sample requires a specific format. SEEK expects three pieces of information for each linked item:
+* id: the numeric identifier assigned by the platform to each Source or Sample.
+    * This identifier is visible directly in the Samples table.
+    * It also appears in the sample’s URL.
+    * You can also retrieve it by exporting the table to CSV ('Export to CSV') or Excel ('Batch download to Excel') — useful when handling many samples.
+* type: the type of asset to link. For this use case, the type is always "Sample".
+* title: the Source name as defined by the user.
+
+To link different Samples, fill the Input column in the Excel file using the following syntax:
 One input value:
 
 ```ruby
@@ -79,13 +90,16 @@ Two input values:
 
 ![create study samples 6]({{ "/images/user-guide/isajson-compliance/create_samples_isastudy_samples_6.png" | relative_url }}){:.screenshot}
 
-Navigate to the same Sources table from the Study design tab, click on "Choose File" button at the bottom of the page, select the saved excel file and click "Upload". Verify and confirm the upload via the pop-up window, then click "Save".
+{% include callout.html type="warning" content="The syntax shown above applies only when linking ISA-JSON compliant Samples within a Study or Assay." %} 
 
-### Create Assay Samples
-In the Assay design tab, Samples can be created in three ways, similar to Study Samples (see above). The only difference is the mandatory column "Input" in the Assay Samples table.
-* For first Assay, it must be filled with valid and existing Study Samples from the same Study.
-* For subsequent Assays, it must be filled with valid and existing Assay Samples from the previous Assay in the same Assay Stream.
+If the Experiment Sample Template includes an attribute such as Registered Sample or Registered Sample List, the linkage might work differently. If the Sample type that is being referenced is non-ISA-JSON compliant, you do not need the full syntax structure. Instead, simply provide the sample ID of the SEEK Sample in the Excel file. 
+Always check the Experiment Sample Template to confirm which attribute type (and Sample Type) is expected before filling in the spreadsheet.
 
+### Create Assay Samples
+In the Assay design tab in [experiment view](viewing-project-in-single-page), Samples can be created in two ways, similar to Study Samples (see above). The only difference is the mandatory column "Input" in the Assay Samples table.
+* The 'Input' of the first Assay must be linked to a valid and existing Study Samples from the same Study. 
+* For subsequent Assays, the 'Input' must be linked to valid, existing Assay Samples from the previous Assay (n-1) in the same Assay Stream.
+In both cases, sample linking via 'Upload Excel spreadsheet' requires the same syntax as described above. 
 
 ## Viewing samples in ISA-JSON compliant Experiments
 Samples in ISA-JSON compliant Experiments can be visualised in the "design" tab (Study or Assay design). Samples are grouped in tables: Study Sources table, Study Samples table, Assay Samples table, Experiment overview.

help/user-guide/create-sample.md

@@ -3,18 +3,18 @@ title: Creating a Sample
 ---
 
 
-You can create a new sample directly in SEEK, or by uploading samples contained within a Sample Type Template.
+You can create a new sample directly in {{ site.seek_instance.name | default: "FAIRDOM-SEEK" }}, or by uploading samples contained within a Sample Type Template.
 
 
-## Creating a Sample Directly in SEEK
+## Creating a Sample directly in {{ site.seek_instance.name | default: "FAIRDOM-SEEK" }}
 
-To create a sample directly in SEEK, select Create and then Sample in the drop down menu.
+To create a sample directly in {{ site.seek_instance.name | default: "FAIRDOM-SEEK" }}, select Create and then Sample in the drop down menu.
 
 ![menu create sample]({{ "/images/user-guide/samples/menu-create-sample.png" | relative_url }}){:.screenshot}
 
 You will be taken to the collection of Sample Types that you can use to generate a Sample.
 The default is the projects you are part of, but you can also search through Sample Types that are generated,
-and publicly available, from other SEEK users.
+and publicly available, from other {{ site.seek_instance.name | default: "FAIRDOM-SEEK" }} users.
 
 ![select sample type]({{ "/images/user-guide/samples/select-sample-type.png" | relative_url }}){:.screenshot}
 

help/user-guide/edit-isa-assays.md

@@ -1,5 +1,5 @@
 ---
-title: Edit an Existing ISA-JSON compliant Assay
+title: Edit an existing ISA-JSON compliant Assay
 ---