====== Metadata Templates ======
As described in the previous sections, every user of the RDMS can easily add metadata to their objects and collections either via the [[rdms:metadata:metadatawebportal|functionality in the web portal]] or using [[rdms:metadata:cli|iCommands]]. Described here is another functionality of the web portal related to metadata management: the use of metadata templates.\\
As the name suggests, metadata templates are pre-configured metadata entry forms that the user can define in order to have **a consistent way of recording metadata** for a given data object or collection. For example, you could have a template attached to a collection recording the "Name of the PI", "Starting date", "Publication state", "Funding agency", etc. Such a template could be used to record information on the projects of a research group, such that the same information is always reliably recorded. Another example would be a template attached to a data object recording the "Acquisition method", "Instrument used", "Temperature", "Humidity", "Reagents", "Researcher responsible", or other values. Such a template could be used to record the instrument settings used to obtain the data object.\\
The advantage of a template over manual entry of metadata is that the user has a pre-defined list of entries. This reduces the risk of forgetting to record a given value or to have objects with different metadata entries, even though they should have been matching.
In the web portal, the menu to access the creation and management of metadata templates is located as shown in Figure 1.
{{ :rdms:metadata:meta_webtemplate_1.png?direct&800 |}}
Figure 1
Once you click on the menu icon, you will be redirected to the ''Metadata Template Settings'' page of the web portal, as shown in Figure 2. Here you can see all metadata templates and types that are available to you and you can build your own templates and types by selecting the green highlighted gear icon.
{{ :rdms:metadata:meta_webtemplate_2.png?direct&800 |}}
Figure 2
On the top of the menu in the red box there are two tabs, for ''Templates'' and ''Metadata Types'' respectively. The primary tab of ''Templates'' is already selected when you first open the ''Metadata Template Settings'' page and lists all the templates that are available to you, either because they are public, they have been shared with you, or because you created them. The second tab for ''Metadata Types'' does the same. If a template or a type has a {{:rdms:metadata:2023-09-07_14-37.png?direct&30|}} icon on their left, it means that you are able to edit the template/type.
In order to create a ''Metadata Type'' or a ''Metadata Template'' click on the gear icon shown in Figure 2 in green. The menu in the red box will appear and you will have the choice to either create a ''Metadata Type'' or a ''Metadata Template''. In the next sections, we will explain how all three options work.
{{ :rdms:metadata:meta_webtemplate_3.png?direct&800 |}}
Figure 3
===== How to Create Metadata Types =====
The RDMS web portal makes standard metadata types available to all users.
The standard types available to all users are:
* ''multiline string'': allows for the input of multiple lines of text.
* ''int'': allows and limits the input to an integer number.
* ''float'': allows and limits the input to a real or decimal number.
* ''date'': allows and limits the input to a date.
* ''string'': allows for the input of a single line of text.
* ''boolean'': allows your entry to be either ''true'' or ''false''.
Should you need to create your own special entry, however, then you can use the ''Create Metadata Types'' functionality to do so. The RDMS web portal also allows you to create two different kinds of ''Metadata types'' as described below. These types merely define what function a metadata entry can have and if restrictions apply to it.
The user-created metadata types are as follows:
The ''Simple metadata type'' is the standard entry type and closely resembles the kind of entry you can have when manually inputting your metadata. It can, however, be slightly more detailed than a simple blank field. In fact, the ''simple type'' can be used to restrict possible values in the templates you create, such as introducing a minimum or a maximum value, or to restrict which values you can choose by creating a drop-down list.
{{ :rdms:metadata:meta_webtemplate_4.png?direct&800 |}}
Figure 4
In Figure 4, all entries with an ''*'' are mandatory, while those without can be left blank. The ''Name*'' and ''Description'' fields serve to name the tag of your metadata entry and provide some context, respectively. The ''Visibility*'' field determines who will be allowed to see and/or use your metadata type. There are four possible values of ''Visibility*'':
* ''Public'': can be used by all RDMS users
* ''Private'': can only be seen and used by the owner and creator of the template
* ''Unknown'': legacy value, please do not use this
* ''Restricted'': not implemented yet, please do not use
The next field is the ''Base Type*'' field. Here you can use one of the standard base types to determine if your metadata entry is going to be text, numbers, a date, etc. Please refer to the above description of the base types for more information. You can also use a metadata type you previously created here as a base type, but please be sure it fits what you want to do.
Finally, ''Validators'' allow to put restrictions on your metadata type. Specifically, you can set a:
* ''Min Value'': Defines the minimum value acceptable for that entry.
* ''Max Value'': Defines the maximum value acceptable for that entry.
* ''Minimum Length'': Defines the minimum length of your entry.
* ''Maximum Length'': Defines the maximum length of your entry.
* ''Enumeration'': This option allows you to create a set of fixed answers that you or whoever compiles your template later can choose from when entering metadata. An example would be having a drop-down menu with three instruments to choose from under the metadata entry "Instrument used to create data object".
* ''Regular Expression'': This setting allows the user to force a certain formatting in the metadata entry if they can write a regular expression according to the rules defined [[https://docs.python.org/3/library/re.html#regular-expression-syntax|here]].
The ''Complex Type'' allows for even more control. While you can see from Figure 5 that the ''Name*'', ''Description'', and ''Visibility'' fields are present as for the ''Simple Type'', the ''Complex Type'' can be used to assign attributes or elements to your metadata templates. This type can be seen as a metadata entry with its own substructure that can be re-used in your templates. For instance; you could create a complex type with values for name, affiliation, address, etc of the contribution authors of a work.
{{ :rdms:metadata:meta_webtemplate_5.png?direct&800 |}}
Figure 5
Finally, we would like to go a little bit more into detail on what ''Attributes'' and ''Elements'' are. As the name suggests, the ''Complex Metadata Type'' can be made up of multiple single entries. We distinguish between two sub-parts for this type. One such sub-part we call ''Attribute'' and it is basically an entry defined by a ''Simple Type''. For this entry, the user can decide if it is a required field (similar to the ones labelled with an ''*'') or not, and not much else.\\
The second sub-part we call ''Element'' and it is an entry that can be characterized by a ''Complex Type'' or a ''Simple Type''. Contrary to an ''Attribute'', this type of entry can have a minimum number of occurrences or a maximum number of them. Ultimately, we would suggest you use ''Attributes'', unless the use of ''Elements'' is required.
===== How to Create Metadata Templates =====
If metadata types are clear to you, you can open the metadata template creation screen by clicking the {{:rdms:metadata:gear_icon.png?direct&20|}} icon on the top right. You can build a template from scratch from the menu that will appear. Select ''Add Metadata Template'' and fill in the name and description you would like in your template. The fields with asterisks ''*'' are mandatory. Figure 6 shows the window for the ''Metadata Template'' creation.
{{ :rdms:metadata:meta_webtemplate_6.png?direct&800 |}}
Figure 6
The fields in the red box describe the template itself. Here you can input the template name, add a brief description, set the visibility of the template, and record its version. As for the ''Metadata Types'', there are four possible values of ''Visibility'':
* ''Public'': can be used by all RDMS users
* ''Private'': can only be seen and used by the owner and creator of the template
* ''Unknown'': legacy value, please do not use this
* ''Restricted'': not implemented yet, please do not use
Clicking on ''Elements'' in the blue box will allow you to add entry fields in your ''Metadata Template''. You can define the entry itself by compiling the fields in the green box, giving it a name, a description and limiting its minimum and maximum number of entries. You can also define the type of metadata entry in the drop-down menu in the purple box. If you don't need your own specific ''Metadata Type'', then you can use the standard types described at the beginning of this page, otherwise refer to the [[:rdms:metadata:metadatatemplates#how_to_create_metadata_types|above section]] to find out how to create your own type. Please keep in mind that your template can contain multiple ''Elements''.\\
Once you are done with your template, click on the blue ''Create'' button at the bottom on the form to save your template.
==== Examples of Template Usage ====
Metadata templates can be used to record many different things about your data and the way you use them is ultimately up to you. We give two brief examples of how to set up a template using both the standard and user-defined types.
For the example using the standard types, we want to attach metadata to a collection in order to record all the collaborators that worked on that project. Remember, you can always do this by manually inputting all the metadata fields yourself, but a template makes this part of the data management so much easier.
++++ Click to display example |
{{ :rdms:metadata:meta_webtemplate_7.png?direct&800 |}}
Figure 7
The template displayed in Figure 7 shows an example where only the basic types are used to create a ''Metadata Template''. To compile this template and attach metadata to a collection, right-click the collection and click ''Add metadata template'' in the menu that will appear (see Figure 8).
{{ :rdms:metadata:meta_webtemplate_8.png?direct&800 |}}
Figure 8
Then click the drop-down menu and select the template you wish to compile, as shown in Figure 9.
{{ :rdms:metadata:meta_webtemplate_9.png?direct&800 |}}
Figure 9
Finally, compile the template and confirm your input by clicking on ''Submit'' (at the bottom of your template) to attach the metadata to your collection (see Figure 10).
{{ :rdms:metadata:meta_webtemplate_10.png?direct&800 |}}
Figure 10
++++
For the use of user-defined types in the creation of a template, we want to create a metadata entry that records what instrument was used to record a certain set of data. We also want to record the instrument settings and put restrictions on certain fields. We also want to make sure that certain metadata entries are always recorded when this specific template is used.
++++ Click to display example |
First we need to create a user-defined type to select our instrument from. Figure 11 shows how to create a ''Simple Type'' that will result in a drop-down menu with three options.
{{ :rdms:metadata:meta_webtemplate_11.png?direct&800 |}}
Figure 11
Next, we need to create our template. Figure 12 shows how to do so, while using our own type for the choice of instrument. Please also notice that we restrict the input of all our variables to just one entry, except for the ''Researcher present'' variable, where we allow for up to five entries. The restriction can be applied either by specifying the number of ''Minimum number of Occurrences'' and ''Maximum number of Occurrences'', or by simply leaving the fields blank. Leaving the fields blank will not make the entry mandatory, however.
{{ :rdms:metadata:meta_webtemplate_12.png?direct&800 |}}
Figure 12
Finally, we can once again navigate to the object we wish to attach metadata to and right-click it. Select ''Add metadata template'' in the menu, as for the previous example, then select the template you want to use. Figure 13 shows how the ''Instrument*'' value, now mandatory because of our restrictions, appears as a drop down menu from which you can select the instrument your data has been generated by. The ''Researcher present'' value will also appear five times in this template, starting from ''Researcher present 0'' and going to ''Researcher present 4''.
**Note**:\\
The web portal will display one value more than the minimum for non-mandatory entries. In our case, ''Researcher present 0'' and ''Researcher present 1'' are immediately displayed in the input form. Instead, ''Researcher 2'', ''Researcher 3'', and ''Researcher 4'' will appear only if the previous fields are filled out, the form saved and then edited again.
{{ :rdms:metadata:meta_webtemplate_13.png?direct&800 |}}
Figure 13
++++