From 8b40b9be603515b25d945e82dc0825033e65729d Mon Sep 17 00:00:00 2001 From: NielsGeudens Date: Wed, 23 Jul 2025 11:40:19 +0200 Subject: [PATCH 1/2] User Documentation to include permissions on Sample Types and ISA Samples. User documentation to include editing of Assays, Studies and Sample types, including what can and cannot be edited. --- _data/sidebars/user_guide.yml | 21 ++++- help/user-guide/create-sample-type.md | 67 +++++-------- help/user-guide/edit-assays.md | 93 ++++++++++++++++++ help/user-guide/edit-sample-type.md | 105 +++++++++++++++++++++ help/user-guide/edit-studies.md | 93 ++++++++++++++++++ help/user-guide/isa-sample-permissions.md | 60 ++++++++++++ help/user-guide/sample-type-permissions.md | 62 ++++++++++++ 7 files changed, 456 insertions(+), 45 deletions(-) create mode 100644 help/user-guide/edit-assays.md create mode 100644 help/user-guide/edit-sample-type.md create mode 100644 help/user-guide/edit-studies.md create mode 100644 help/user-guide/isa-sample-permissions.md create mode 100644 help/user-guide/sample-type-permissions.md diff --git a/_data/sidebars/user_guide.yml b/_data/sidebars/user_guide.yml index f2fa76719..936de959d 100644 --- a/_data/sidebars/user_guide.yml +++ b/_data/sidebars/user_guide.yml @@ -85,10 +85,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 @@ -147,16 +151,25 @@ subitems: - title: Sample types description: Creating and browsing samples, and samples in ISA-JSON compliant experiments. subitems: - - title: Create a Sample Type + - 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 - 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 diff --git a/help/user-guide/create-sample-type.md b/help/user-guide/create-sample-type.md index bab4b1a4c..e4a02ab41 100644 --- a/help/user-guide/create-sample-type.md +++ b/help/user-guide/create-sample-type.md @@ -4,25 +4,20 @@ 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. 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) . 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. @@ -30,38 +25,35 @@ First we will show generating a Sample type through manually creating a sample t 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. support@fair-dom.org -* **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. support@fair-dom.org; +* **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: @@ -117,11 +109,4 @@ When a Sample is shared outside of a Project, but is still not accessible public 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) diff --git a/help/user-guide/edit-assays.md b/help/user-guide/edit-assays.md new file mode 100644 index 000000000..c64b363ed --- /dev/null +++ b/help/user-guide/edit-assays.md @@ -0,0 +1,93 @@ +--- +title: Edit an Existing 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 attributes + +Each Assay contains 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. diff --git a/help/user-guide/edit-sample-type.md b/help/user-guide/edit-sample-type.md new file mode 100644 index 000000000..58074d1d6 --- /dev/null +++ b/help/user-guide/edit-sample-type.md @@ -0,0 +1,105 @@ +--- +title: Edit an existing Sample Type +--- + +To edit a Sample Type, the user must have Edit or Manage permissions (i.e. ST-policy ≥ Edit). For details on assigning permissions, see the [Sample Type Permissions](sample-type-permissions) page. + +Steps to edit: + +1. Navigate to Browse → Sample Types; +2. Select the Sample Type to edit; +3. Click Actions → Edit Sample Type in the top-right corner. + +> {% include callout.html type="note" content="Users are not notified of changes made to the Sample Type — inform collaborators as needed." %} + + +## Changing Sample Type properties + +Users with appropriate permissions may modify the following properties: + +- Title: The name used to identify the Sample Type; +- Description: A summary describing the purpose or scope; +- Associated Projects: Determines visibility and access for project members; +- Tags: Labels used for categorization and filtering. + +Changes are applied immediately upon saving and do not affect existing samples or their (meta)data. + +## Changing Sample Type attributes + +Each Sample Type consists of a list of attributes that define the metadata fields for its samples. + +### 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. + +Attributes can be added even after samples exist, except when the Sample Type was created via file-upload import. Any Sample Type that was populated via a file‐upload import carries an association back to the Data File, and that import record prevents further attribute additions. The idea is to preserve the 1:1 mapping between the columns in the Data File and the attributes on the Sample Type. Consequently, attributes cannot be added. + +It is not possible to create a new mandatory attribute from scratch if the Sample Type already has associated samples. In that case, the existing samples would have empty values for the mandatory attribute. Instead, create the new attribute as optional and add the relevant metadata to the associated Samples. Once all Samples have non-empty values for the attribute, it is possible to make the attribute mandatory. + +### Removing an attribute + +An attribute can be deleted only if no existing samples contain a value for it. If values exist, the 'Remove' button will not be shown. To proceed, delete the metadata values from all associated samples first. + +### Modifying 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 that attribute; +- Attribute type can be changed only if no samples have a value for that attribute; +- 'Required?' flag: + - Changing from mandatory to optional is always allowed; + - Changing from optional to mandatory is allowed only if all samples already contain a non-empty value. + +## Validation & best practices + +- Each Sample Type must have exactly one attribute marked as the title; +- Attribute titles must be unique within the Sample Type; +- The title attribute cannot be of type 'Registered Sample Multi'; +- The Sample Type must not be locked. + +## Deleting a Sample Type + +To delete a Sample Type: + +1. Navigate to Browse → Sample Types; +2. Select the Sample Type; +3. Click Actions → Delete Sample Type in the top-right corner. + +Deletion is only permitted if: + +- The user has Manage permissions; +- The Sample Type has no associated samples; +- The Sample Type is not referenced by another Sample Type, Study or Assay. + +If these conditions are not met, the 'Delete Sample Type' option will not be available. + + +## Troubleshooting & tips + +- Missing “Remove” button next to an attribute? + → Ensure no samples contain a value for that attribute. + +- “Add new attribute” button is missing + → Check whether the Sample Type was populated via file‑upload import. SEEK locks the schema to preserve column‑to‑attribute mappings. + +- Cannot rename or change type/unit of an attribute + → Verify that no samples have populated values for that field. + +- Toggling “Title” status is greyed out** + → You can only switch the title flag if **every** existing sample has a non‑empty value for the new title attribute. + +- Toggling “Required?” status is greyed out** + → You can only switch the required flag if **no** existing sample has a non‑empty value for the attribute. + +- “Delete Sample Type” action missing** + → Confirm that: + 1. You have 'Manage' permissions; + 2. No samples exist for that type; + 3. It isn’t referenced by any other Sample Type, Study or Assay. \ No newline at end of file diff --git a/help/user-guide/edit-studies.md b/help/user-guide/edit-studies.md new file mode 100644 index 000000000..70e283cb6 --- /dev/null +++ b/help/user-guide/edit-studies.md @@ -0,0 +1,93 @@ +--- +title: Edit an Existing Study +--- + + +To edit an existing Study, the user must have Edit or Manage permissions (i.e. policy ≥ Edit). + +### Steps to edit + +1. Navigate to the Study; +2. Click Actions → Edit ISA Study in the top-right corner. + +> {% include callout.html type="note" content="Users are not notified of changes made to the Study — inform collaborators as needed." %} + +## Modifying Study properties + +Users with appropriate permissions may update the following properties: + +- **Title**: The name used to identify the Study; +- **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 Study attributes + +Each Study contains two 'Sample Types', namely a Study Source and a Study Sample. Both consist 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 Study. + +The 'Overview' tab of the Study displays the associated Experiment Sample Templates and indicates 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 Study Source or Study Sample 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 Study Study/Sample must have exactly one attribute marked as the title; +- Attribute titles must be unique within the Study Source/Sample; +- The title attribute cannot be of type Registered Sample Multi; +- The Study 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. diff --git a/help/user-guide/isa-sample-permissions.md b/help/user-guide/isa-sample-permissions.md new file mode 100644 index 000000000..0f748bd49 --- /dev/null +++ b/help/user-guide/isa-sample-permissions.md @@ -0,0 +1,60 @@ +--- +title: ISA-JSON Compliant Sample Permissions +--- + +ISA-JSON compliant Samples (referred to as *ISA-JSON Samples*) are created within an [Assay](assays) or [Study](studies) using an [Experiment Sample Template](isajson-templates). These samples are defined by metadata attributes, units, and validation rules specified in the template. + + + +## Permission levels + +| **Permission level** | **View** | **Edit** | **Manage** | **Description** | +|----------------------|:--------:|:--------:|:----------:|------------------| +| **No access** | ❌ | ❌ | ❌ | The sample is completely hidden. | +| **View** | ✅ | ❌ | ❌ | The sample is visible but cannot be modified. | +| **Edit** | ✅ | ✅ | ❌ | The sample metadata can be updated. | +| **Manage** | ✅ | ✅ | ✅ | Full control: edit, delete, and change permissions. | + +Each permission level defines what actions a user can perform on an ISA-JSON Sample: + +- No access: The sample is entirely hidden from the user; +- View: The user can view the sample and its metadata but cannot make changes; +- Edit: The user can update metadata fields but cannot delete the sample or modify its sharing policy; +- Manage: The user has full control, including editing, deleting, and changing permissions. + +## Inheritance and sharing behavior +Each ISA-JSON has an associated sharing policy that determines which users or groups can view, edit, or manage it. Though alligned by default, these permissions can be set independently of those assigned to the parent Assay or Study, which may have their own sharing settings. + +> {% include callout.html type="note" content="When both an Assay/Study and its ISA‑JSON Samples have policies, SEEK enforces the most restrictive. Even if you can view an Assay, an individual Sample with 'No access' will remain hidden." %} + +## Who can create ISA-JSON Samples? + +> {% include callout.html type="note" content="Upgrading from a lower to higher policy at the level of the Assay or Study does **not** automatically grant ISA-JSON Sample‑creation rights." %} + +To create ISA-JSON Samples, a user must: + +- Be a member of **at least one** project (not necessarily the one linked to the Assay or Study). +- Have at least 'View' access to the parent Assay or Study. + +For instructions on creating ISA-JSON Samples, refer to the [Samples in ISA-JSON Compliant Experiments](create-sample-isajson-compliant#create-assay-samples) page. + +## Setting ISA-JSON Sample permissions +### Via the Sample browser + +- Navigate to Browse → Samples; +- Use the filters to locate the desired ISA-JSON Sample; +- Click Actions → Manage Sample to update its permissions. + +### From the Assay or Study experiment view + +- Open the [experiment view](viewing-project-in-single-page) of the relevant Assay or Study; +- Select one or more ISA-JSON Samples using the checkboxes; +- Click Batch sharing permissions at the bottom of the Dynamic Table. + +### From the User profile + +- Go to 'My profile'; +- Use the [batch permission tools](bulk-change-sharing-permission) to manage access across multiple assets, including ISA-JSON Samples; +- Tip: Click **Sort by ISA** to group assets by Investigation → Study → Assay → Sample. + +> {% include callout.html type="note" content="Batch sharing will **overwrite** all existing custom sharing policies for the selected Samples. Use with caution." %} diff --git a/help/user-guide/sample-type-permissions.md b/help/user-guide/sample-type-permissions.md new file mode 100644 index 000000000..2ef0d41ca --- /dev/null +++ b/help/user-guide/sample-type-permissions.md @@ -0,0 +1,62 @@ +--- +title: Sample Type Permissions +--- + +In FAIRDOM-SEEK, a Sample Type defines the structure and metadata schema for a group of related samples. It specifies the attributes, units, and validation rules that apply to samples created under it. + +Each Sample Type has an associated sharing policy that determines which users or groups can view, edit, or manage it. These permissions are distinct from those of the individual samples, which have their own independent sharing settings. + + +## What can users do at each permission level? + +| **Permission level** | **View ST** | **Edit ST** | **Manage ST** | **What this means** | +|----------------------|:-----------:|:-----------:|:-------------:|----------------------| +| No access | ❌ | ❌ | ❌ | The Sample Type is completely hidden. | +| View | ✅ | ❌ | ❌ | Users can see the Sample Type, but not change it. | +| Edit | ✅ | ✅ | ❌ | Users can update fields, attributes, and units. | +| Manage | ✅ | ✅ | ✅ | Full control: delete, change policy, etc. | + + +In other words: +- No access: The Sample Type is completely hidden, the user won’t even know it exists; +- View: The user can look at the Sample Type and its details, but can’t make any changes; +- Edit: The user can make changes to the Sample Type (like updating fields or units), but can’t delete it or change who else can see it; +- Manage: The user has full control — they can edit, delete, and change sharing settings. + +> {% include callout.html type="note" content="Samples have their own, independent sharing policies that do not default to those of their Sample Type." %} + +Permissions assigned to a Sample Type do not automatically apply to the individual samples created under it. Each sample is governed by its own sharing policy, which is configured independently of the Sample Type. +By default, newly created samples are private. + +Note: Samples created within the context of a Study or Assay **do** inherit the permissions of that Study or Assay by default. + +## Who can create Samples? + +> {% include callout.html type="note" content="Upgrading from a lower to higher policy at the level of the Sample Type does **not** automatically grant sample‑creation rights." %} + +To create samples, a user must: + +- Be a member of **any** project (not necessarily the one linked to the Sample Type); +- Have at least View access to the Sample Type. + +## How to set Sample Type permissions + +1. Go to 'Browse → Sample Types'; +2. Click the Sample Type you want to configure; +3. Click 'Actions → Manage Sample Type' in the top right corner; +5. Choose a level: No access, View, Edit, or Manage; +6. *(Optional)* Use custom sharing to add specific users or groups; +7. Click 'Update' — your changes apply immediately. + + +## Troubleshooting & Tips + +- Can't see the “Create Sample” button? + → Make sure you have View access and belong to a project. + +- Can't edit a Sample Type? + → You need Edit or Manage rights and must be in a project. + +- Want to hide old Sample Types? + → Set their policy to No access. + From acf62efaa72ef2b779fbfbd2b7d0a72643687ff4 Mon Sep 17 00:00:00 2001 From: floradanna <51486716+floradanna@users.noreply.github.com> Date: Wed, 20 Aug 2025 09:55:08 +0000 Subject: [PATCH 2/2] review PR --- _data/sidebars/user_guide.yml | 34 ++++++++++------------ help/user-guide/create-sample-type.md | 12 +------- help/user-guide/edit-assays.md | 6 ++-- help/user-guide/edit-sample-type.md | 2 +- help/user-guide/edit-studies.md | 8 ++--- help/user-guide/sample-type-permissions.md | 2 +- 6 files changed, 26 insertions(+), 38 deletions(-) diff --git a/_data/sidebars/user_guide.yml b/_data/sidebars/user_guide.yml index 936de959d..3c36a1132 100644 --- a/_data/sidebars/user_guide.yml +++ b/_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 @@ -141,6 +136,17 @@ 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 @@ -148,15 +154,7 @@ subitems: 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: 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 + - title: Samples subitems: - title: Creating a Sample diff --git a/help/user-guide/create-sample-type.md b/help/user-guide/create-sample-type.md index e4a02ab41..b764d2fd7 100644 --- a/help/user-guide/create-sample-type.md +++ b/help/user-guide/create-sample-type.md @@ -4,7 +4,7 @@ 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. @@ -98,15 +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. diff --git a/help/user-guide/edit-assays.md b/help/user-guide/edit-assays.md index c64b363ed..e92c6b391 100644 --- a/help/user-guide/edit-assays.md +++ b/help/user-guide/edit-assays.md @@ -1,5 +1,5 @@ --- -title: Edit an Existing Assay +title: Edit an Existing ISA-JSON compliant Assay --- @@ -22,9 +22,9 @@ Users with appropriate permissions may update the following properties: Changes are applied immediately upon saving and do not affect existing samples or their metadata. -## Modifying Assay attributes +## Modifying Assay Sample Type's attributes -Each Assay contains a list of metadata attributes used to describe its samples. Attributes may be: +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. diff --git a/help/user-guide/edit-sample-type.md b/help/user-guide/edit-sample-type.md index 58074d1d6..701b0e96b 100644 --- a/help/user-guide/edit-sample-type.md +++ b/help/user-guide/edit-sample-type.md @@ -2,7 +2,7 @@ title: Edit an existing Sample Type --- -To edit a Sample Type, the user must have Edit or Manage permissions (i.e. ST-policy ≥ Edit). For details on assigning permissions, see the [Sample Type Permissions](sample-type-permissions) page. +To edit a Sample Type, the user must have Edit or Manage permissions. For details on assigning permissions, see the [Sample Type Permissions](sample-type-permissions) page. Steps to edit: diff --git a/help/user-guide/edit-studies.md b/help/user-guide/edit-studies.md index 70e283cb6..51dc3d5eb 100644 --- a/help/user-guide/edit-studies.md +++ b/help/user-guide/edit-studies.md @@ -1,9 +1,9 @@ --- -title: Edit an Existing Study +title: Edit an Existing ISA-JSON compliant Study --- -To edit an existing Study, the user must have Edit or Manage permissions (i.e. policy ≥ Edit). +To edit an existing ISA-JSON compliant Study, the user must have Edit or Manage permissions (i.e. policy ≥ Edit). ### Steps to edit @@ -22,9 +22,9 @@ Users with appropriate permissions may update the following properties: Changes are applied immediately upon saving and do not affect existing samples or their metadata. -## Modifying Study attributes +## Modifying Study Sample Types' attributes -Each Study contains two 'Sample Types', namely a Study Source and a Study Sample. Both consist of a list of metadata attributes used to describe its samples. Attributes may be: +Each ISA-JSON compliant Study contains two 'Sample Types', namely a Study Source and a Study Sample. Both consist 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 Study. diff --git a/help/user-guide/sample-type-permissions.md b/help/user-guide/sample-type-permissions.md index 2ef0d41ca..b780e381f 100644 --- a/help/user-guide/sample-type-permissions.md +++ b/help/user-guide/sample-type-permissions.md @@ -2,7 +2,7 @@ title: Sample Type Permissions --- -In FAIRDOM-SEEK, a Sample Type defines the structure and metadata schema for a group of related samples. It specifies the attributes, units, and validation rules that apply to samples created under it. +In FAIRDOM-SEEK, a Sample Type (ST) defines the structure and metadata schema for a group of related samples. It specifies the attributes, units, and validation rules that apply to samples created under it. Each Sample Type has an associated sharing policy that determines which users or groups can view, edit, or manage it. These permissions are distinct from those of the individual samples, which have their own independent sharing settings.