Create and Use Sample Templates 🧪
- Video Overview
- Create a brand-new template
- Create a Template from a Sample
- Create a Sample from a Template
- View a Sample's Template
- Browse Templates
- Search Templates
- Edit a Template
- Add a new Field to a Template
- Delete an existing Field from a Template
- View all Samples Created from a Template
- Update a Specific Sample to a New Template Version
- Update All Samples to New Template Version
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.
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
- When viewing a sample, click on Create Template from the context menu.
- 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; you can edit this later. Click on Create Template once you are happy.
- 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.
- In the sidebar, select Create > Sample.
- Select the sample template you want from the template list. You can use the info button on the right of the template entries to view what fields that template has. The arrows at the bottom-right of the table let you browse through templates.
- The template fields will now be available for you to fill in.
View a Sample's Template
- When viewing a sample, click on the Source template to directly open the template; alternatively, you can click the info button under Sample Template to quickly overview the template fields.
- If you've clicked on Source, you'll open the template the sample is based on.
- If you've clicked on Sample Template, you'll be able to quickly overview the template fields, and open the template through the link on the top-right.
Click on Templates in the sidebar to browse a list of all templates that you have access to.
To restrict a global search to only show templates, click on "Type" filter, and select Templates.
Edit a Template
- When viewing a template, click on Edit:
- 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.
- 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.
- For choice or radio fields, you can also add or remove possible values.
- Once you are done editing, click on Save.
- 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
- When editing a template, scroll to the bottom of the Fields section and select Add new field.
- You'll then be able to specify the name of the 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.
- 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 editing a template, scroll to the field you want to delete, and click 'X' button in the right corner of the field area.
- 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.
- 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.
- 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 a New Template Version
- When viewing a sample, select the info button next to the template information.
- If the sample is based on a template that has since been updated, you will have the option to Update the sample to the latest version. You can also click on the template global ID on the top-right to view what the template version currently used by this sample looks like.
- 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 Samples to New Template Version
- When viewing the template, select Info, then Update Samples in the sidebar that appears.
- Click on Update All if you are happy with how updating the template version will affect your samples.
- 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
Here is a set of rules that are applied when updating a Sample (S) to a newer template version (T).
In brief, these attempt to apply changes if they are compatible with existing data and won't delete or remove existing data unless the template owner explicitly decide otherwise.
- Check difference between T and S properties:
- If T has new subsample alias, update subsample alias of S
- 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 there is new option set:
- if the S field value is valid with new T option set, update the S field option set
- if the S field value is not valid with new T option set, REJECT WHOLE UPDATE ATTEMPT FOR THIS SAMPLE
- for each T field, if there is no connected S field (i.e. it's a new field added to T):
- add the field to S, with empty value (even if T field has a default value, it shouldn't be used)