Create and Use Sample Templates 🧪

Inventory Beta is available to all existing and new Team and Enterprise customers, and will be available to Community users in the near future. Learn more at the RSpace Inventory Hub.

Introduction

When working with samples, you might add custom fields to a sample to include relevant information about it, and notice that you're regularly duplicating that sample to reuse the same custom fields for new samples. This is where using sample templates comes in handy.

Templates can be created from scratch, or from existing samples. 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.

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 Template from the context menu.
  2. 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.
  1. 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.

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.

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 is the name that subsamples that originate from a sample using this template will have, as well as 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 More 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.
  4. 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 in newly added field, 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 user.

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 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 sample to latest template may remove an existing field if the user who modified the template explicitly decided so when deleting the template field, and if the latest template has new fields these fields will be added to the sample with empty value (rather than default one).

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)

Powered by HelpDocs (opens in a new tab)