Create and Use Sample Templates 🧪

Inventory is available to all existing and new Team and Enterprise customers at no extra cost, learn more at the RSpace Inventory Hub.

Introduction

You can make individual samples based on sample templates, or bulk import samples and create a new sample templates using a .csv file (see Import Samples into Inventory). A sample is a type of item, or a description of the common characteristics of some related family of subsamples. A sample is always made up of one or more similar or identical subsamples. The subsample is the physical item itself. Subsamples have a physical location (e.g. a container), while samples are a conceptual category and do NOT have physical locations, since each sample might be made up of multiple subsamples, and each subsample could have a different location. Metadata can be applied to a whole family of items using the sample page, but each subsample can also have it's own more specific metadata that applies only to that single item.

When working with samples, you might want to add custom fields to help users include relevant information and improve reproducibility and consistency by making sure that all samples of a specific type use the same custom fields. This is where using sample templates comes in handy.

Sample templates can be created from scratch, created from existing samples, or created using a properly formated .csv file. By creating a template and editing it to your liking, you are able to reuse the structure of a specific sample for future samples. This enables you to create samples with a consistent format, as well as ensuring that fields that are required for safety or regulatory purposes are included for each sample of that type.

After editing the template, existing samples based on this template can be updated to latest template version, which will propagate changes to the structure of a sample (e.g. add new template fields), but won't modify any data already saved in the existing samples.

Each RSpace deployment has a number of default templates, visible to everyone. You can make a copy of these templates, which makes you an owner of the copy, and allows further editing to your needs.

Templates created by a system administrator are visible to everyone on the server; user-created templates are only visible to LabGroups they belong to.

Video Overview

The following video goes over the template features described in this article:

Create a brand-new template

Click on 'Create -> Template' on the left-hand navigation bar:

You now see the template editor appear. You can set the units of measurement, subsample name and default values, as well as add new fields (see the section 'Editing Templates' below for details).

Create a Template from a Sample

  1. When viewing a sample, click on Create from the context menu.
  2. The create dialog will open. Click the Create button at the bottom of the dialog.
  3. You can now give your template a name. The template will contain all of the fields of the sample. You can use the checkboxes to select which template fields should have default values taken from the sample; unchecked fields will be left blank on the new template. Once created, the default values for template fields can be edited at any time.
    Click on Create Template once you are happy.
  4. Your template will be created, and you can now use it when creating samples.

Create a Sample from a Template

Now you've created the template, it can be used to create Samples from it.

  1. In the sidebar, select Create > Sample.
  2. Select the sample template you want from the template list. The arrows at the bottom-right of the table let you browse through templates. You can also search the list of templates for the one you want.
  3. The template fields will now be available for you to fill in.
A sample can also be created directly from a template, by opening/selecting the template and then clicking the Create button in the context menu. The create dialog (below) will open and you will be able to proceed with sample creation.

View a Sample's Template

  1. When viewing a sample, click on the Template's Global ID link under Sample Template.
  2. This will open the template the sample is based on.

Browse Templates

Click on Templates in the sidebar to browse a list of all templates that you have access to.

Screenshot of just the sidebar and left panel. A listing of all template it shown, with the templates link in the sidebar circled.

Search Templates

To restrict a global search to only show templates, click on "Type" filter, and select Templates.

Edit a Template

Values from the template are considered defaults when creating a new sample from that template. As a general rule, template values are only used during creation of a new sample. That means changing value in the template definition will not change already existing samples, e.g. changing description of a template will not update description of already existing samples based on that template. The same rule applies to template fields, e.g. if you update Default Value of a field it will only be used when creating a new sample, and will not be propagated to existing samples.
Note that when a template is updated, existing samples that were created from the template are still based on previous version of the template. After new template version is saved you can choose to update a specific sample or all samples to the latest template version, which will propagate structural changes (e.g. add new fields) to existing samples.
  1. When viewing a template, click on Edit:
  2. You can specify a Subsample Alias, which indicates how you want to refer to subsamples that originate from the sample created using this template. Remember that in RSpace a samples is a set of related or identical subsamples. The subsample is the physical item, the sample is just a description of the item or items. You should also specify what Unit Type and Default Scale the samples should use. If none of the available options are suitable, you can specify your own custom value: in that case, make sure you enter both the singular and plural forms for it.
    Alias
  3. Under Custom Fields, you can change the name and default value for a field, as well as move the field up or down in the list. You can also add a new field, or delete pre-existing one, this is described lower down on this page.
  1. For choice or radio fields, you can also add or remove possible values.
  1. Once you are done editing, click on Save.
  2. Your template will be updated. Note that existing samples that were created from this template will not be automatically updated. You can update the samples by clicking "Yes" on the "Update existing samples?" popup; you can also update all samples or specific samples later, as described lower down on this page.

Add a new Field to a Template

A new template field will be added to existing samples when updating them to latest template version, but the field will not have any value (even if you set default value in the template field). That's to ensure that samples only contain data explicitly set by the sample owner, and to avoid situation where data seems to unexpectedly "appear" in the sample (as a side-effect of changes to template definition).
  1. When editing a template, scroll to the bottom of the Fields section and select Add new field.
  2. You'll then be able to specify the name of the field, decide whether it is a mandatory field (i.e. all samples created from the template must have a value for this field), its data type, optionally give the field a default value, and move the field up or down the list. Once you are done, click on Save.
Note, that adding a new mandatory field will block you from updating existing samples to latest template version. That's because update to latest template never changes data of existing sample, so it won't add any value for mandatory field (even if the template defines default value for that field).

If there are existing samples based on your template and you want to add a new mandatory field, first add a field as non-mandatory, then update existing samples to latest template version, set the value for newly added field in existing samples, then update template field again to make it mandatory.
  1. Your template will be saved, and any new samples created from this template will have this new field. Note that existing samples that were created from this template will not be automatically updated. You can update the samples by clicking "yes" on the Update existing samples popup; you can also update all samples or specific samples later, as described lower down on this page.

Delete an existing Field from a Template

When deleting template field you'll need to decide if field should be deleted from existing samples when these samples are updated to latest template version.
  1. When editing a template, scroll to the field you want to delete, and click 'X' button in the right corner of the field area.
  2. There are two variants of deletion that decide whether the field should, or should not, be deleted from pre-existing samples based on the template. If 'Remove field from existing samples' variant is selected, the pre-existing samples will have the field deleted when they are updated to latest template version.
  3. After selecting a deletion variant you'll see a confirmation that the field is going to be deleted. You can continue editing the template, as the field is not actually deleted until you Save.
  4. Once you are done, click on Save. Your template will be saved, and any new samples created from this template will not have the deleted field. Existing samples that were created from this template will not be automatically updated; you can update them by clicking "yes" on the Update existing samples popup; you can also update all samples or specific samples later, as described lower down on this page.

View all Samples created from a Template

When viewing a template, scroll down to the bottom to see a list of all samples created from that template. You can also perform a search, or use advanced search to view samples owned by a specific individual.

You can also click on Info, then select Show Samples to instantly scroll down to this section.

Update a specific Sample to latest Template Version

  1. When viewing a sample, the template from which it was defined is linked under the section called "Sample Template". If the sample is based on a template that has since been updated, an "Update" button will be shown. Here, this sample is defied using version 2 of the Antibody template, which can be viewed by tapping the versioned Global ID link, and it can be updated to the latest version with a single tap.
  2. Your sample will then be updated to the latest template version, following the rules below with any changes to the template reflected in the sample.

Update all of your Samples to latest Template Version

  1. When viewing the template, select Info, then Update Samples in the sidebar that appears.
  2. Click on Update All if you are happy with how updating the template version will affect your samples.
  3. You will get a confirmation that your samples have been updated. You can click on the dropdown arrow in the notification to expand it and obtain direct links to the samples that were updated.

Rules for applying template changes to existing Samples

As a general rule updating a given sample to latest template will not modify any data stored in that sample. Only structural changes (for example, adding or deleting of fields) will be applied, assuming these changes are compatible with data stored in that sample. Updating a sample to latest template will remove an existing field if the person who modified the template explicitly decided that updated samples should loose the fields when deleting the template field. Updating a sample to latest template will add fields if the latest template has new fields, with an empty value being set.

In particular, changes to Default Value of template field won't be applied to field value of existing samples. The default values are only used when creating new sample. Data in existing samples can be only updated by editing these samples - individually or with batch edit.

Below is an exact set of rules that are applied when updating a Sample (S) to a new version of the Template (T).

  1. Check difference between T and S properties:
    • if T has new subsample alias, update subsample alias of S
  2. For each S field check difference between S field and connected T field:
    • if the connected T field was deleted with 'Remove field from existing samples' option, delete the S field
    • if the connected T field was renamed, rename the S field
    • if the connected T field is radio/choice, and the set of possible radio/choice options has changed:
      • if the option selected in S is valid with new set of possible options from T, update the set of possible options in S
      • if the option selected in S is not valid with new set of possible options from T, REJECT WHOLE UPDATE ATTEMPT FOR THIS SAMPLE
  3. for each T field, if there is no connected S field (i.e. it's a new field added to T):
    • if the new T field is not mandatory, add the field to S, with empty value (even if T field has a default value, it won't be used)
    • if the new T field is mandatory, REJECT WHOLE UPDATE ATTEMPT FOR THIS SAMPLE


How did we do?


Powered by HelpDocs (opens in a new tab)