Documentation: Permissions on Sample Type and ISA

_data/sidebars/user_guide.yml

@@ -36,9 +36,7 @@ subitems:
         url: /help/user-guide/bulk-change-sharing-permission
       - title: Making an Investigation, Study or Assay citable
         url: /help/user-guide/investigation-snapshots
-  -
-    #hr: true
-    title: Yellow Pages/Directory
+  - title: Yellow Pages/Directory
     description: Directory of common project tasks.
     subitems:
       - title: "Programme"
@@ -61,9 +59,7 @@ subitems:
 #       url: ""
 #     - title: "[People]"
 #       url: ""
-  -
-    #hr: true
-    title: Experiments
+  - title: Experiments
     description: Generating the ISA structure, designing an ISA-JSON compliant experiment, making items citable.
     subitems:
     - title: Introduction to the ISA structure
@@ -72,9 +68,8 @@ 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
-      url: /help/user-guide/isa-json-compliant-experiment
-    - hr: true
+      - title: ISA-JSON compliant experiments
+        url: /help/user-guide/isa-json-compliant-experiment
     - title: Investigations
       subitems:
       - title: Creating an ISA-JSON compliant investigation
@@ -85,10 +80,14 @@ subitems:
       subitems:
       - title: Creating an ISA-JSON compliant study
         url: /help/user-guide/studies
+      - title: Editing an ISA-JSON compliant study
+        url: /help/user-guide/edit-studies
     - title: Assays
       subitems:
       - title: Creating an ISA-JSON compliant assay
         url: /help/user-guide/assays
+      - title: Editing an ISA-JSON compliant assay
+        url: /help/user-guide/edit-assays
     - title: Experiment Sample Templates
       subitems:
       - title: Creating Experiment Sample Templates
@@ -137,26 +136,38 @@ subitems:
 #      url: ""
 #    - title: Events
 #      url: /help/user-guide/general-attributes#events
+  -
+    #hr: true
+    title: Samples type
+    description: Creating and browsing samples, and samples in ISA-JSON compliant experiments.
+    subitems:
+    - title: Creating a Sample Type
+      url: /help/user-guide/create-sample-type
+    - title: Editing a Sample Type
+      url: /help/user-guide/edit-sample-type
+    - title: Sample Type permissions
+      url: /help/user-guide/sample-type-permissions
   -
     #hr: true
     title: Samples
     description: Creating and browsing samples, and samples in ISA-JSON compliant experiments.
     subitems:
     - title: Introduction to samples
       url: /help/user-guide/samples
-    - title: Sample types
-      description: Creating and browsing samples, and samples in ISA-JSON compliant experiments.
-      subitems:
-      - title: Create a Sample Type
-        url: /help/user-guide/create-sample-type
+
     - title: Samples
       subitems:
-      - title: Create a Sample
+      - title: Creating a Sample
         url: /help/user-guide/create-sample
-      - title: Working with samples in ISA-JSON compliant Experiments
-        url: /help/user-guide/create-sample-isajson-compliant
       - title: Legacy Biosamples
         url: /help/user-guide/legacy-biosamples
+    - title: ISA-JSON compliant Samples
+      subitems:
+      - title: Creating ISA-JSON compliant Samples
+        url: /help/user-guide/create-sample-isajson-compliant
+      - title: Managing ISA-JSON compliant Samples
+        url: /help/user-guide/isa-sample-permissions
+
   -
     #hr: true
     title: General attributes and links

help/user-guide/create-sample-type.md

@@ -4,64 +4,56 @@ title: Create a Sample Type
 
 Sample Types are templates that detail the key information that needs to be included to describe a given sample correctly.
 
-By default, any member of a Project may create a Sample Type and associate with that Project. By default the Sample Type will only be visible to members of that
- project until it has publicly accessible Samples associated with it. See [Sample Type Visibility](#sample-type-visibility) .
+By default, any member of a Project may create a Sample Type and associate with that Project. See [Sample Type Permissions](#sample-type-permissions).
 
 A SEEK Administrator can change the configuration such that Sample Types can only be created by the Project Administrator.
 
-
 To create a new sample type, select create from the drop down menu, and then select Sample Type from the list
 
 ![menu create sample type]({{ "/images/user-guide/samples/menu-create-sample-type.png" | relative_url }}){:.screenshot}
 
 A Sample Type can be made in two ways
 
-* By manually defining the attributes using a form
+* By manually defining the attributes using a form;
 * Uploading a spreadsheet that contains a Sample Template.
 
-
-
-
-## Creating a Sample Type manually using a Form
+## Creating a Sample Type manually using a form
 
 First we will show generating a Sample type through manually creating a sample type. To begin with ensure that the Form is selected.
 
 ![sample type form]({{ "/images/user-guide/samples/sample-type-form.png" | relative_url }}){:.screenshot}
 
 Sample Type allows you to include:
 
-* [Title](general-attributes#title)
-* [Description](general-attributes#description)
-* [Projects](general-attributes#projects)
-* [Tags](general-attributes#tags)
+* [Title](general-attributes#title);
+* [Description](general-attributes#description);
+* [Projects](general-attributes#projects);
+* [Tags](general-attributes#tags).
 
 
 You can define your own attributes for the Sample Type.
 We would recommend using Minimum Information Checklists to assist in deciding the attributes you will need to include in your Sample Type.
 
-## Defining Attributes
+## Defining attributes
 
 All attributes must have a Name, and a selected Type.
 
-
 You can define the different types of data that the attributes should be:
 
-
-* **String**: a sequence of characters (e.g Blue)
-* **Text**: A longer alphanumerical entry (e.g. The 4th experiment in the batch, it was sampled late, so may not be as accurate).
-* **Integer**: a whole number; not a fraction (e.g. 1, 2, 3, 4)
-* **Date**: A selected date (e.g. 2nd December 2016)
-* **Date time**: a selected date and time (e.g. 2nd December 2016 at 14:00 GMT)
-* **Real number**: A number that can be a fraction and include a decimal place, e.g 1.25
-* **Web link**: a link to a specific web page (e.g. https://fair-dom.org)
-* **Email address**: e.g. [email protected]
-* **CHEBI ID**: An identification for a specific chemical structure registered in the ChEBI database (https://www.ebi.ac.uk/chebi/) (e.g. CHEBI:17234)
-* **Boolean**: a true/false declaration, 1 or 0 can also be accepted.
-* **SEEK strain**: an internal link to a strain registered within SEEK.
-* **SEEK sample**: an internal link to a sample registered within SEEK.
-* **URI**: A Uniform Resource Identifier, which for example may relate to an ontology term
-* **Controlled Vocabulary**: An attribute can be a set of predefined terms you have to select from, and any other term is invalid. You can either create a new
-controlled vocabulary or reuse and existing one. In the future we will be adding ontology support the the controlled vocabularies.
+* **String**: a sequence of characters (e.g Blue);
+* **Text**: A longer alphanumerical entry (e.g. The 4th experiment in the batch, it was sampled late, so may not be as accurate);
+* **Integer**: a whole number; not a fraction (e.g. 1, 2, 3, 4);
+* **Date**: A selected date (e.g. 2nd December 2016);
+* **Date time**: a selected date and time (e.g. 2nd December 2016 at 14:00 GMT);
+* **Real number**: A number that can be a fraction and include a decimal place, e.g 1.25;
+* **Web link**: a link to a specific web page (e.g. https://fair-dom.org);
+* **Email address**: e.g. [email protected];
+* **CHEBI ID**: An identification for a specific chemical structure registered in the ChEBI database (https://www.ebi.ac.uk/chebi/) (e.g. CHEBI:17234);
+* **Boolean**: a true/false declaration, 1 or 0 can also be accepted;
+* **SEEK strain**: an internal link to a strain registered within SEEK;
+* **SEEK sample**: an internal link to a sample registered within SEEK;
+* **URI**: A Uniform Resource Identifier, which for example may relate to an ontology term;
+* **Controlled Vocabulary**: An attribute can be a set of predefined terms you have to select from, and any other term is invalid. You can either create a new controlled vocabulary or reuse and existing one. In the future we will be adding ontology support the the controlled vocabularies.
 
 ![sample type attributes]({{ "/images/user-guide/samples/sample-type-attributes.png" | relative_url }}){:.screenshot}
 
@@ -86,10 +78,10 @@ When creating the sample type, first choose the tab _Use spreadsheet template_
 
 On the initial Sample Template page you can include the following metadata:
 
-* [Title](general-attributes#title)
-* [Description](general-attributes#description)
-* [Projects](general-attributes#projects)
-* [Tags](general-attributes#tags)
+* [Title](general-attributes#title);
+* [Description](general-attributes#description);
+* [Projects](general-attributes#projects);
+* [Tags](general-attributes#tags);
 
 and then also select Choose File to select a sample template to upload:
 
@@ -106,22 +98,5 @@ At least one attribute must be required and set to the title, and other attribut
 
 Once completed click update. Your Sample Type can now be used to generate Samples.
 
-## Sample Type Visibility
-
-Initially, a Sample Type is only visible and accessible to members of the Project it is associated with.
-
-However, once a Sample Type has instances of Samples associated with them, and those Samples are shared publically (i.e. to logged out members), the Sample Type
-also becomes visible.
-
-When a Sample is shared outside of a Project, but is still not accessible publicly, then the Sample Type will adopt the visibility of the referring Sample
-when accessed via a link. For example if a Sample is shared with another Project, a member of that other Project may view the Sample Type when clicking the link
-the link from the Sample description. However, in this case, the Sample Type won't appear in lists or search results.
-
-## Editing Sample Types
-
-The Sample Type may be edited by the original creator, or somebody that can administer the related projects.
-
-If no samples have yet been created, you can freely edit the Sample Type and its attributes. Once Samples have been created for a Sample Type, it is no longer possible to modify the attributes - however other details about the Sample Type can be changed.
 
 
-For details on how to create a Sample please go to [Creating a Sample](create-sample)

help/user-guide/edit-assays.md

@@ -0,0 +1,93 @@
+---
+title: Edit an Existing ISA-JSON compliant Assay
+---
+
+
+To edit an existing Assay, the user must have Edit or Manage permissions (i.e. policy ≥ Edit).
+
+### Steps to edit
+
+1. Navigate to the Assay;
+2. Click Actions → Edit ISA Assay in the top-right corner.
+
+> {% include callout.html type="note" content="Users are not notified of changes made to the Assay — inform collaborators as needed." %}
+
+## Modifying Assay properties
+
+Users with appropriate permissions may update the following properties:
+
+- Title: The name used to identify the Assay;
+- Description: A summary describing the purpose or scope;
+- Associated Assets: Including [SOPs](sops), [Publications](publications), and Documents.
+
+Changes are applied immediately upon saving and do not affect existing samples or their metadata.
+
+## Modifying Assay Sample Type's attributes
+
+Each ISA-JSON compliant Assay contains one Sample Type consiting of a list of metadata attributes used to describe its samples. Attributes may be:
+
+- Inherited from an [Experiment Sample Template](isajson-templates);
+- Defined locally within the Assay.
+
+The 'Overview' tab of the Assay displays the associated Experiment Sample Template and and allows to identify which attributes are inherited.
+
+### Adding an attribute
+1. Click the green 'Add new attribute' button at the bottom of the attributes table;
+2. Provide the following:
+   - Name (must be unique);
+   - Required (toggle on/off);
+   - Title (toggle on/off);
+   - Attribute Type (e.g., Text, Number, Date, Controlled Vocabulary);
+   - Description, PID, Unit (optional);
+3. Click 'Update' to apply changes.
+
+> Note: If the Assay already contains samples, new attributes must be created as optional. Once all samples have non-empty values for the attribute, it can be marked as mandatory.
+
+### Removing an attribute
+
+An attribute can be removed only if:
+
+- No samples contain a value for the attribute;
+- The attribute is **not inherited** from an Experiment Sample Template.
+
+If these conditions are not met, the 'Remove' button will not be displayed. To proceed, check the Experiment Sample Template and/or delete the metadata values from all associated samples first.
+
+### Editing an attribute
+
+The following rules apply when modifying attributes:
+
+- Name, Description, and Unit can be changed at any time;
+- Title status can be toggled only if all samples contain a value for the attribute;
+- Attribute type can be changed only if:
+  - No samples contain a value for the attribute;
+  - The attribute is not inherited from an Experiment Sample Template;
+- Required flag:
+  - Changing from **mandatory to optional** is always allowed;
+  - Changing from **optional to mandatory** is allowed only if all samples contain a non-empty value;
+- ISA Tag*:
+  - Cannot be changed for inherited attributes;
+  - Can be freely changed for non-inherited attributes if no samples exist;
+  - If samples exist, the ISA tag can only be changed if no sample contains a value for the attribute.
+
+> *Note: The ISA tag determines how SEEK labels the attribute when [exporting to ISA‑JSON](exporting-experiments-as-isajson). Setting the correct ISA tag ensures compatibility with downstream ISA-aware tools.
+
+## Validation & best practices
+
+- Each Assay must have exactly one attribute marked as the title;
+- Attribute titles must be unique within the Assay;
+- The title attribute cannot be of type 'Registered Sample Multi';
+- The Assay must not be locked.
+
+## Troubleshooting & Tips
+
+- Missing “Remove” button next to an attribute?
+  → Check the attributes of the associated Experiment Sample Template and ensure no samples contain a value for that attribute.
+
+- Cannot rename or change type/unit of an attribute? 
+  → Check the attributes of the associated Experiment Sample Template and verify that no samples have populated values for that field.
+
+- Toggling “Title” status is disabled?
+  → All samples must have a non-empty value for the new title attribute.
+
+- Toggling “Required?” status is disabled?
+  → You can only switch to mandatory if all samples already contain a value for the attribute.