diff --git a/docs/_static/img/how-to-guide/condition_page.png b/docs/_static/img/how-to-guide/condition_page.png new file mode 100755 index 0000000..389dbe2 Binary files /dev/null and b/docs/_static/img/how-to-guide/condition_page.png differ diff --git a/docs/_static/img/how-to-guide/condition_question.png b/docs/_static/img/how-to-guide/condition_question.png new file mode 100755 index 0000000..a4f794e Binary files /dev/null and b/docs/_static/img/how-to-guide/condition_question.png differ diff --git a/docs/_static/img/how-to-guide/condition_settings.png b/docs/_static/img/how-to-guide/condition_settings.png new file mode 100755 index 0000000..3af186c Binary files /dev/null and b/docs/_static/img/how-to-guide/condition_settings.png differ diff --git a/docs/_static/img/how-to-guide/task_project_page.png b/docs/_static/img/how-to-guide/task_project_page.png new file mode 100755 index 0000000..a2f25f7 Binary files /dev/null and b/docs/_static/img/how-to-guide/task_project_page.png differ diff --git a/docs/_static/img/how-to-guide/task_settings_date.png b/docs/_static/img/how-to-guide/task_settings_date.png new file mode 100755 index 0000000..f7596bc Binary files /dev/null and b/docs/_static/img/how-to-guide/task_settings_date.png differ diff --git a/docs/_static/img/how-to-guide/task_settings_general.png b/docs/_static/img/how-to-guide/task_settings_general.png new file mode 100755 index 0000000..f4e0517 Binary files /dev/null and b/docs/_static/img/how-to-guide/task_settings_general.png differ diff --git a/docs/conf.py b/docs/conf.py index d1b2212..447d679 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -105,7 +105,7 @@ # documentation. # html_theme_options = { - 'navigation_depth': 3, + 'navigation_depth': 4, 'collapse_navigation': False, 'style_external_links': True, } diff --git a/docs/management/catalog-development.md b/docs/management/catalog-development.md index 487a5ed..444c80e 100644 --- a/docs/management/catalog-development.md +++ b/docs/management/catalog-development.md @@ -2,20 +2,19 @@ ## Introduction -This document is a guide to creating catalogues. It contains step-by-step instructions for creating a simple Catalog. If you have never created a Data Management Plan (DMP) catalogue in RDMO, it is recommended that you work through these steps on your own instance of RDMO. -You will be introduced to important RDMO concepts, terminology, structure, hierarchies and dependencies, and can then apply this knowledge to create your own catalogue. -RDMO is a tool for creating DMPs. A DMP is a documentation of the RDM practices of your research project over the entire data lifecycle. RDMO offers several DMP catalogues, whether for a specific funder or discipline, or just generic templates for any research project. A Catalog is a set of questions about data management practices throughout the data lifecycle, so it's a comprehensive set of questions to think about and document all the data and data management practices for your research project. +This document is a guide to creating catalogues. It contains step-by-step instructions for creating a simple Catalog. If you have never created a Data Management Plan (DMP) catalogue in RDMO, it is recommended that you work through these steps on your own instance of RDMO. You will be introduced to important RDMO concepts, terminology, structure, hierarchies and dependencies, and can then apply this knowledge to create your own catalogue. + +RDMO is a tool for creating DMPs. A DMP is a documentation of the RDM practices of your research project over the entire data lifecycle. RDMO offers several DMP catalogs, whether for a specific funder or discipline, or just generic templates for any research project. A Catalog is a set of questions about data management practices throughout the data lifecycle, so it's a comprehensive set of questions to think about and document all the data and data management practices for your research project. Specialist users of RDMO with administrative rights (or have the role of editor) can customise the Catalog or create new Catalogs. Before deciding to create a new Catalog, you should check whether you have the rights to do so and whether there is already a catalogue that meets your needs. ## Explanation of the general relationships -### Hierarchy of the elements of a Catalog (Some might also call it Questionnaire or Interview, depending on the version, they are working on.) +*Hierarchy of the elements of a Catalog* -Catalog +Some might also call it Questionnaire or Interview, depending on the version, they are working on. ![Overview of the RDMO Hierarchy](../_static/img/how-to-guide/hierarchy.PNG) - > *Overview of the RDMO Hierarchy* Catalogs consist of (thematically distinct) Sections, which may span multiple pages. Pages are essentially (the entire scrollable area of) screens containing the questions (possibly organised into question sets). Questions can be of different types, distinguished by the type of response expected (e.g. text box, checkbox, date picker or range slider). @@ -33,7 +32,7 @@ Before we can start creating our new [*Catalog*](#catalog), we need to make sure * Check that you can see `Management` in the top navigation bar. If so, you are an Editor and can create a new Catalog. * The newly installed RDMO instance is still empty, i.e. there are no questionnaires, attributes, views, etc. available. -### If required/necessary: Import Attributes +### Import Attributes If not already done, import the default [*Attributes*](#attributes) first (you will need them later): @@ -50,7 +49,7 @@ If not already done, import the default [*Attributes*](#attributes) first (you w If Attributes, Options, and Option sets are imported and they already exist, they will be updated. Any local customisation of the default Attributes / Options will be overwritten. ``` -### If required/necessary: Import options and [*Option sets*](#option-sets) +### Import options and [*Option sets*](#option-sets) If not already done, import the default option sets: @@ -58,7 +57,7 @@ If not already done, import the default option sets: * Go to the `Management` section and `import` the "optionsets.xml" file in the same way as you imported the attributes before. RDMO will again show you a summary of all the option sets being imported. * Continue with the import button. -## Step-by-Step guide to a first Catalog +## Building your first Catalog In this guide we will show you how to create a simple catalog to help you get started. We will show you how to create a catalog with two sections and two pages. All the steps we provide can be repeated to create a full catalog. @@ -73,7 +72,7 @@ In the end, the Catalog should look something like this mockup: ![](../_static/img/how-to-guide/empty_page.PNG) > *Empty Project Page* -The Page on the left shows the Question about the funding body, and the Page on the right allows users to create different tabs (one for each dataset). For information about the creator(s) of the dataset(s), different creators can be added using the green button. +The Page on the left shows the Question about the funding body, and the Page on the right allows users to create different tabs (one for each dataset). For information about the creator(s) of the dataset(s), different creators can be added using the button below the last creator. ### Initial setup @@ -82,9 +81,6 @@ You should see a screen like this when you open RDMO: ![](../_static/img/how-to-guide/first_page.PNG) > *First Page after Login* - -## Creating a new Catalog - Click on `Management` in the top navigation bar. In a fresh RDMO it will look like this: ![](../_static/img/how-to-guide/creating_catalog.PNG) @@ -96,9 +92,9 @@ Check that the heading under management is [*Catalogs*](#catalog), if not click While many RDMO instances will already have existing [*Catalogs*](#catalog), this guide assumes that the RDMO instance is completely empty. This ensures that our screenshots are free of distracting elements, making it easier to focus on the process. If your instance contains some catalogs, that’s fine — this example will still apply. ``` -### Step one: Create a new Catalog +### Creating a new Catalog -Now let us create a new [*Catalog*](#catalog). Click on the green `New` button. You should now see something like this: +Now let us create a new [*Catalog*](#catalog). Click on the `New` button at the top-right corner. You should now see something like this: ![](../_static/img/how-to-guide/createCatalog_1st_page.PNG) > *Creating a Catalog - Overview* @@ -133,7 +129,7 @@ If you also see the `Sites` and `Editors` fields , you are on a hosted RDMO serv For the next step, click on `Create and continue editing` at the bottom of the page. -### Step two: Creating Sections +### Creating Sections We will now add a first [*Section*](#sections) to this [*Catalog*](#catalog). Note that you can reuse an already existing *Section* from other [*Catalogs*](#catalog) available on your RDMO instance. Here we will create a new *Section*. @@ -155,7 +151,7 @@ At the top of the web page you should now see that the section is being used in ![](../_static/img/how-to-guide/used_sections.PNG) > *Indicator how often a Section is used in different Catalogs* -### Step three: Creating a Page +### Creating Pages We will now create our first [*Page*](#pages). An RDMO page contains [*Questions*](#questions) that are presented to the user on a single web page/screen. Think of a *Page* as the analogue of an actual paper page in a classic questionnaire. We recommend that you do not put too many questions on a page \- users do not like to scroll. @@ -173,14 +169,13 @@ To create a Page, click Create Page in the Section we created in the previous st ![](../_static/img/how-to-guide/createPage_buttons.PNG) > *Creating a Page* -#### What we do not need to fill in: +**What we do not need to fill in:** Note that we do *not* check if it `is collection`, we do *not* fill in the `Name` field, and we do *not* assign an `Attribute`. You only need these fields if the page is to be a Collection. We will explain what this means in detail when we create our second page. We will also ignore the `Conditions` part for now. This feature allows us to show or hide pages (and [*Question sets*](#question-sets) and [*Questions*](#questions)) depending on the user's answers to previous questions. We will skip this feature for this basic guide. -### Add elements to our *Page*: Questions - +### Adding Questions to Pages We will now add a new element to our page. Elements can be [*Questions*](#questions) or *Question sets*. In our example, we want to use this first [*Page*](#pages) to ask [*Questions*](#questions) on the project’s funding, so we will click on `Create new question` in the *Elements* area. ![](../_static/img/how-to-guide/add_elements.PNG) @@ -209,7 +204,7 @@ https://rdmorganiser.github.io/terms/domain/project/funder/name * You can now click on the `Create` button. This [*Question*](#questions) form will close and you will be returned to the [*Page*](#pages) you came from. Click `Save` to save your changes. -### Step four: Creating a Page as a Collection +### Creating Pages as a Collection Now we are going to create a second [*Page*](#pages) that will be a [*Collection*](#collection). In our example, we want to use this page to ask [*Questions*](#questions) about the datasets created in a project. @@ -271,19 +266,18 @@ This is very useful if your questionnaire is longer. We will not use it in the s * Now click on the button `Create and continue editing`. -#### What we do not need to fill in: +**What we do not need to fill in:** We will also ignore the `Conditions` part for now. This feature allows us to show or hide pages (and [*Question sets*](#question-sets) and [*Questions*](#questions)) depending on the user's answers to previous questions. We will skip this feature for this basic guide. -### Add elements to our *Page*: Question set +### Adding Question sets to Pages -We are now going to add new elements to our page. Elements can be [*Questions*](#questions) or a [*Question set*](#question-sets). In our example, we want to use this second page to contain a *question set* that collects information about datasets, so we click on `Create new question set` in the *Elements* area. +We are now going to add new elements to our page. Elements can be [*Questions*](#questions) or a [*Question set*](#question-sets). In our example, we want to use this second page to contain a *question set* that collects information about datasets. We could add existing ones by clicking on ´Add existing element´ in the *Elements* area, but in this case we will click on `Create new question set`. ![](../_static/img/how-to-guide/add_elements.PNG) > *Adding Elements to the Page* - -### Create a new question set +### Creating a new Question set Again, there are several fields we need to fill in to create a new [*Question set*](#question-sets). @@ -292,7 +286,7 @@ Again, there are several fields we need to fill in to create a new [*Question se ![](../_static/img/how-to-guide/qs_comment.PNG) > *Create a Question Set* -* Since a dataset can have more than one creator, we want to be able to add (additional) creators. So we will make this [*Question set*](#question-sets) a [*Collection*](#collection). This will cause RDMO to display a green button to add another question block like this: +* Since a dataset can have more than one creator, we want to be able to add (additional) creators. So we will make this [*Question set*](#question-sets) a [*Collection*](#collection). This will cause RDMO to display a button below the block to add another question block like this: ![](../_static/img/how-to-guide/q_example.PNG) > *Exemplary Question for Collections* @@ -304,7 +298,7 @@ Again, there are several fields we need to fill in to create a new [*Question se * Now click on `Create and continue editing`. -### Adding a first question to our question set +### Adding Questions to Question sets We are going to add a [*Question*](#questions) that asks for the name of the contributor. To do this, we click on the `Create new question` button. If we do this in the context of our current [*Question set*](#question-sets), the [*Question*](#questions) will automatically be linked to the question set. @@ -321,7 +315,7 @@ We are going to add a [*Question*](#questions) that asks for the name of the con * The [`Widget type`](#widget-type) allows you to define the type and the answer choices of your current [*Question*](#questions). E.g. `Textarea` for long answers, `Text` for short answers, or `Radio buttons` for predefined answers. We will look at radio buttons later when we add a second [*Question*](#questions) to this [*Page*](#pages). Here we will choose `Text`, as usually only one line is needed for names. * Now click on `Create`. This should take you back to the [*Question set*](#question-sets). You should also see that the [*Question set*](#question-sets) now has one item: the [*Question*](#questions) we just created. -### Adding a second *Question* to our *Question set* +**Adding a second Question to our Question set** Let us add a second [*Question*](#questions): @@ -353,7 +347,7 @@ But it is not ideal, as the semantics indicate that it is the e-mail address of * Click on the edit (pencil) icon to edit the *Page*. -### Add a *Question* to our *Page* +### Adding Questions to Pages We will now add another new element, a [*Question*](#questions), to our *Page*. * Click on `Create new question` in the *Elements* area. @@ -407,7 +401,7 @@ This picture shows the entire structure of the [*Catalog*](#catalog). This repre You are now in the overview of all your available projects. In our case, this is an empty list. -## Creating a first project with the new catalog +### Creating a first project with the new catalog Click on `New project` @@ -431,16 +425,16 @@ Create a first *Dataset* by clicking on the `+Dataset` button (this will generat ![](../_static/img/how-to-guide/select_dataset.PNG) > *Add a new dataset to your anwsers* -The [*Page*](#pages) should now display our [*Question set*](#question-sets) for the creators and the single [*Question*](#questions) regarding storage volume. The title you gave the dataset should now be displayed in a tab, and you can add more tabs (for more datasets) by clicking on the `+Dataset` tab. Recall: this is why we ticked the `is collection` box in the [*Page* form](#step-four-creating-a-page-as-a-collection). +The [*Page*](#pages) should now display our [*Question set*](#question-sets) for the creators and the single [*Question*](#questions) regarding storage volume. The title you gave the dataset should now be displayed in a tab, and you can add more tabs (for more datasets) by clicking on the `+Dataset` tab. Recall: this is why we ticked the `is collection` box in the [*Page* form](#creating-a-page-as-a-collection). -You can fill in the first creator's data. Note that there should be a green button to `+ Add Creator`. Press it and see if an additional field for a second creator appears. +You can fill in the first creator's data. Note that there should be a button to `+ Add Creator`. Press it and see if an additional field for a second creator appears. ![](../_static/img/how-to-guide/ds_creator.PNG) > *Add a new Creator* Finally, you should see a radio button menu. The available options are defined in the [*Optionset*](#option-sets) that we linked when [setting up the question](#add-elements-to-our-page-questions). If we wanted different options, e.g. different data volumes, we would have to create a new [*Optionset*](#option-sets). -### How to add Options to your RDMO +## How to add Options to your RDMO If you have never created a [*Catalog*](#catalog) in RDMO before, we recommend you start with the step-by-step guide to [Creating a new Catalog](#creating-a-new-catalog). Creating new [*Options*](#options) is easier than creating a new questionnaire, but knowing the parts of a questionnaire (called a *Catalog* in RDMO) will help you understand what *Options* are for. @@ -452,9 +446,9 @@ In this example, we want to offer users a selection of experimental techniques f First, navigate to the *Management* section in RDMO. This can be done by clicking on *Management* in the top navigation bar. Then click on *Option sets* in the navigation area on the right. -Click on the green *New* button to start creating a new *Option set*. +Click on the *New* button at the top-right corner to start creating a new *Option set*. -The top fields in the form *URI Path* and *URI Prefix* should be familiar from creating *Catalogs* \- if not, have a look at [this section](#step-one-create-a-new-catalog). +The top fields in the form *URI Path* and *URI Prefix* should be familiar from creating *Catalogs* \- if not, have a look at [this section](#creating-a-new-catalog). The comment field can be used to give RDMO managers an idea of what the option set is about and how it will be used. We enter *"This option set provides various experimental methods for omics research. Intended for offering users a specialised selection of methods used to create a generated dataset."* @@ -474,17 +468,17 @@ Click "Create new option". ### Creating a new option -1. Again fill in the *URI Path* and, if empty, the *URI Prefix*. +* Again fill in the *URI Path* and, if empty, the *URI Prefix*. -2. Next, fill in the *Text* (this is what RDMO will display to users) \- it should be short. We choose "DNA Methylation Assay". +* Next, fill in the *Text* (this is what RDMO will display to users) \- it should be short. We choose "DNA Methylation Assay". -3. Optionally, you can also enter the *Help* text for users. This additional text will be displayed in light grey with the *Option* *Text*. +* Optionally, you can also enter the *Help* text for users. This additional text will be displayed in light grey with the *Option* *Text*. -4. The *View text* is only used by RDMO in views and can be used to provide a more detailed text for the option. +* The *View text* is only used by RDMO in views and can be used to provide a more detailed text for the option. -5. Next, the *Additional input* field must be selected. We do not need a text field or a text area for this option, so we select "-----". We will use a different choice later in this guide. +* Next, the *Additional input* field must be selected. We do not need a text field or a text area for this option, so we select "-----". We will use a different choice later in this guide. -6. Finally, click *Create*. +* Finally, click *Create*. ### Creating a second new option with additional input @@ -523,7 +517,235 @@ Finally, we need to use the option in a Question. If you already know how to add If you do not know how to do this: Go through the [Creating a new Catalog](#creating-a-new-catalog) tutorial, except in the [Add a *Question* to our *Page*](#add-elements-to-our-page-questions) step, you can add your new *Question set* instead of the one suggested there. The question text won't fit exactly, but you will see your *Question set* in action. -## Basics +## Understanding Attributes + +* *Attributes* are at the heart of RDMO, linking content elements to project values. They play a crucial role in ensuring consistency and interoperability across different [*Catalogs*](#catalog) and RDMO instances. +* The answers given by a user are stored in this attribute and are not lost. This can be an advantage, as the answers will be displayed even if the user changes the catalog within a project created in RDMO. At the same time, however, there is a potential for danger: + * If you use a particular attribute for a certain question in the first catalog, but the same attribute for a different type of question in another catalog, the answers that were first entered by the user first will be retained, but may no longer make sense. If the user overwrites them in the second catalog, they will no longer make sense for the first catalog when they switch again. + +![](../_static/img/how-to-guide/wrong_attributes.PNG) +> *One Attribute for different Contexts* + + * The answers stored in the attributes are only exchanged within a project. If the user creates another project in which they answer a different catalog, no information is transferred. +* The RDMO domain contains 304 (01/25) hierarchically ordered attributes covering most aspects of RDM. +* The attributes are logically divided into three parts: + +1. URI Prefix: A character string structured as an URL. The default RDMO URI Prefix is the address of the institution, such as „https://your-institution.de/terms“. + +2. Element type (in this case "/domain/") + +3. URI Path + +a) URI Path: The path provides information about the content of the question, with the scope being defined more and more concretely through the hierarchical structure. Separated by slashes, you work your way forward until you reach the “key”. As the name of the attribute should reflect the information expected when answering the question, the scope can be narrowed down. + +- For example, if you want to ask who is the project manager for a project, proceed from the general to the specific as follows: All in all, these are project-specific questions. So the top level of the path is the “project”. Then you want to get general information about its coordination, so you select “coordination” next. As you are looking for a person, the next level would be “name”. The full attribute is then “ https://rdmorganiser.github.io/terms/domain/project/coordination/name”. + +b) URI Key: The key within the path is the last word, which is separated by a slash, and represents the most concrete level for identifying the question. + +- The URI path can be very short, containing only a few terms, or it can be very long, depending on how many levels there are. It is advisable not to make the structures too specific so that the area does not become too small and the attributes can be better used. + +* When creating a catalog, each [*Question*](#questions) must use an attribute, which appears only once in it. +* [*Question sets*](#question-sets) can also be linked to an attribute as well. The default attribute here is "https://rdmorganiser.github.io/terms/domain/project/dataset/id". + * The use of attributes for Question sets does not affect the questions presented to users. Only when the „is collection“-Button is enabled can the user create „datasets“ when answering the catalog: + +![](../_static/img/how-to-guide/set.PNG) +> *Provide Datasets* + +* Overview of existing *Attributes* and usage: [Attribute Overview](https://rdmorganiser.github.io/terms/) + +### How to choose an Attribute + +There is no best practice on how to choose an attribute so far. If you’re not sure, please contact the RDMO group. + +* The steps you can take are the following: + * Review Existing *Attributes*: Familiarize yourself with the [RDMO domain](https://github.com/rdmorganiser/rdmo-catalog/blob/master-rdmo2.x/rdmorganiser/domain/attributes.xml), which contains 304 (01/2025) hierarchically ordered attributes. Identify the specific information your [*Question*](#questions) is trying to capture and look for *Attributes* that closely match your intent. *Attributes* in RDMO are organized in a tree-like structure, so navigate through the hierarchy to find the most relevant category. You can also have a look into [RDMO Terms](https://rdmorganiser.github.io/terms/) to find questions and their related attributes. + * Check *Attribute* Properties: Each *Attribute* has properties such as URI, key, and parent. Ensure these properties align with the context of your [*Question*](#questions). Example: The *Attribute* with the path `project/schedule/project_start` represents the start date of a project. The *Attribute* key is `project_start`. Its parent *Attribute* is the `project/schedule` *Attribute*, which itself is a sub-Attribute of `project`. When creating a [*Page*](#pages) [*Collection*](#collection), you should select the appropriate *Attribute*. ![Overview of available Attributes][image27] + +**Cases where you'll need to create a new Attribute:** + +* Be sure that there is no matching attribute\! Even if the name of an attribute does not literally reflect the question, they are open enough to cover similar question content. For example, if you want to query when a campaign starts (instead of a project), you can still use the attribute “https://rdmorganiser.github.io/terms/domain/project/schedule/project_start” (if you have not already used it in the catalog), because you want to have similar pieces of information. + * Discipline-Specific Information: when capturing data unique to your field that isn’t covered by existing *Attributes*. Example: Specialized lab techniques or data formats or Institution-Specific Requirements: For information specific to your institution’s policies or processes. + * New RDM Aspects: + If addressing a new area of Research Data Management not currently in the existing *Attribute* set. + * If you have created a new attribute, the catalog is no longer so easy to reuse. When setting up an RDMO instance or a release, only the attributes that are in the domain are implemented + * You can contact the RDMO group and ask to include your attribute in the domain as well. + * You must provide the .xml including your attributes when sharing the catalog. The document describing the attributes has to be uploaded before the catalog. When sharing the “XML full” catalog, this remark is not relevant. + +## How to use Conditions in your Catalog + +RDMO offers the option of skipping or hiding questions that are not relevant to users with the help of *Conditions*. This is controlled by a so-called decision question. For example, if users click on the answer option “No, no sensitive data is used”, the subsequent questions about sensitive data are automatically skipped. If a question has multiple answer options, a different condition can be selected for each option, resulting in different behaviour depending on the answer selected. For example, different *Questions sets* can be displayed or skipped. Conditions are always linked to [*Option sets*](#option-sets), [*Questions*](#questions), or [*Tasks*](#tasks) and disable or enable them. They can also be used in [*Views*](#views). + +We strongly recommend that you only create and use [*Conditions*](#conditions) after you have compiled a complete list of [*Questions*](#questions), because [*Conditions*](#conditions) cause [*Questions*](#conditions) to be skipped or hided. If you create and use [*Conditions*](#conditions) too early, this can have the unintended effect of your questions not being displayed in the [*Catalog*](#catalog). + +### How to create new Conditions + +First, navigate to the *Management* section in RDMO. This can be done by clicking on `Management` in the top navigation bar. Then click on `Conditions` in the navigation area on the right and all [*Conditions*](#conditions) available will appear. You can filter the *Conditions* using search terms, or by the URI prefixes used or the site in the case of a multi-site instance. + +Click on the *New* button in the top-right corner to start creating a new *Condition*. + +The top fields in the form *URI Path* and *URI Prefix* should be familiar from creating *Catalogs* \- if not, have a look at [this section](#creating-a-new-catalog). + +The comment field can be used to give RDMO managers an idea of what the [*Condition*](#conditions) is about and how it will be used. We enter *"This condition checks whether sensitive data being handled in the project"* + +You can use the ``Locked` checkbox to prevent the *Condition* from being changed. We leave it unchecked. + +![](../_static/img/how-to-guide/condition_settings.png) +> *All condition settings* + +The Source defines which [*Attribute*](#attributes) is evaluated by the *Condition.* You select an *Attribute* from the *Catalog* (or you can create a new *Attribute*), and the value stored for this *Attribute* in the project is compared against the *Condition*’s target value. Whatever value the user enters or selects for that *Attribute* will be used in the comparison. + +The *Relation* defines **how** the value of the source *Attribute* is compared to the target value. The *Condition* relations include: + +| Relation | Description | Target
(Text) | Target
(Option) | +|-----------------------------|-----------------------------------------------------------------|:----------------:|:-------------------:| +| **is equal to (==)** | Checks whether the answer
is exactly this text or option | ✓ | ✓ | +| **is not equal to (!=)** | Checks whether the answer
is any text or option other than this one | ✓ | ✓ | +| **contains** | Checks whether the text answer
contains the given text fragment | ✓ | – | +| **is greater than (>)** | Checks whether the numeric answer
is greater than the given value | ✓ | – | +| **is greater than or equal (>=)** | Checks whether the numeric answer
is greater than or equal to the given value | ✓ | – | +| **is less than (<)** | Checks whether the numeric answer
is less than the given value | ✓ | – | +| **is less than or equal (<=)** | Checks whether the numeric answer
is less than or equal to the given value | ✓ | – | +| **is empty** | Checks whether no answer has been given | – | – | +| **is not empty** | Checks whether any answer has been given | – | – | + +The last two relational operators **is empty** and **is not empty** do not require a target value. + +The *Target* is the value the source attribute is compared against. Depending on the attribute, this may be: + +* *Text*: a string, boolean value or number to compare with the attribute value +* *Option*: one of the predefined options (in *Option Sets*) associated with the attribute + +The correct type of target depends on the attribute’s configuration in the *Catalog*. + +#### Conditions with a Target Text (including strings, boolean values, numbers) + +In RDMO, text targets are used not only for strings but also for boolean values and numbers, depending on the type of the source attribute. + +*Text values*: For attributes that store plain text, the target is a literal string. Text comparisons are case-sensitive meaning that uppercase and lowercase letters must match exactly for a condition to evaluate as true. This allows precise control when checking specific text values but also requires that the target be entered exactly as the attribute value appears. + +As relation you can choose between + +* is equal to +* is not equal to +* contains + +*Boolean values*: Boolean attribute values are represented as numeric strings (1 = yes, 0 = no). Use these values as the target when you want the *Condition* to check whether a user selected **yes** or **no** in a boolean question. + +As relation you can choose between + +* is equal to +* is not equal to + +*Numbers*: For numeric attributes, the target must be a plain number. These targets are written as plain numbers without additional formatting. + +As relation you can choose between + +* is equal to +* is not equal to +* is greater than +* is greater than or equal +* is less than +* is less than or equal + +#### Conditions with a Target Option + +In addition to targeting text answers, [*Conditions*](#conditions) can also be used to check selected options. In the condition settings, you can select a specific option in *Target (Option)*. For this to work correctly, do not add any text to the *Target (Text)* setting. + +Not all relations work with options, you can choose between two relations for *Target (Options)*: + +* is equal to +* is not equal to + +You can not select multiple options. + +#### Select *Editors* (only in multi-site instance of RDMO) +In a multi-site RDMO installation, you can control which user groups are allowed to edit a [*Condition*](#conditions). Under *Editors*, you can link one or more groups of *Editors*. Only members of the assigned groups will be able to modify the Condition. + +### How to add a condition to your Catalog + +#### Adding *Conditions* to *Sections*, *Pages* or *Question Sets* + +* Open the *Section*, *Page* or *Question Set* where you would like to add the condition +* Scroll down to *Conditions* and Click on `Add existing condition`. A drop-down menu will appear containing all the conditions available on your RDMO instance. +* Click on the drop-down menu and type the name of the condition you created +* After selecting your condition, click on `save` + +![](../_static/img/how-to-guide/condition_page.png) +> *Add a condition to a page* + +#### Adding *Conditions* to *Questions* + +* Open the *Question* where you would like to add the *Condition* +* Scroll down to *Conditions* and Click on `Add existing condition`. A drop-down menu will appear containing all the conditions available on your RDMO instance. +* Click on the drop-down menu and type the name of the condition you created +* After selecting your condition, click on `save` + +![](../_static/img/how-to-guide/condition_question.png) +> *Add a condition to a question* + +```{admonition} Info +If you add multiple [*Conditions*](#conditions) to a [*Question*](#questions), all conditions are combined with a logical OR, which means, if just one of those conditions is met, the element is visible. +``` + +## Adding Tasks to your RDMO + +Using tasks you can add an additional layer to your RDMO [*Catalog*](#catalogs). Tasks are visible directly on the project page and can help users remember important data management tasks. Users can open a task to view its detailed description and see the related question in the interview. + +Each task is linked to a [*Condition*](#conditions) and to specific [*Catalogs*](#catalogs). When the condition is met, the task is displayed and users can interact with it and change its status (open, in progress, closed). This can be used, for example, to display a "Contact your Data Protection Officer" task when a user indicates in the interview that personal data will be collected during the research project. In addition, you can also use tasks for other purposes, e.g. to show recommendations, when a user selects certain options. + +For each task you can define a time frame based on the project’s start and end dates. Tasks can then be displayed relative to these dates, for example one or two months after the project starts or ends. + +![](../_static/img/how-to-guide/task_project_page.png) +> *A task on the project page* + +### How to create new Tasks + +First, navigate to the *Management* section in RDMO. This can be done by clicking on `Management` in the top navigation bar. Then click on *Tasks* in the navigation area on the right and all [*Tasks*](#tasks) available will appear. You can filter the *Tasks* using search terms, or by the URI prefixes used or the site in the case of a multi-site instance. + +Click on the *New* button in the top-right corner to start creating a new *Task*. + +The top fields in the form *URI Path* and *URI Prefix* should be familiar from creating *Catalogs* \- if not, have a look at [this section](#creating-a-new-catalog). + +The comment field can be used to give RDMO editors an idea of what the *Task* is about and how it will be used. We enter *"This task reminds users to identify the rights owner and to contact them if the answer in the catalog indicates that this was not done yet."* + +You can use the *Locked* checkbox to prevent a *Task* from being modified. By default, it is left unchecked. +The `*Available* button indicates whether the task is visible to users. If unchecked, the task will not appear in the user’s task list. +The *Order* determines the position of the task within the list of all existing tasks. You can choose any number that makes sense. + +Next, you can add the short and meaningful title (e.g. *"Contact rights owner"*) and a description (field 'text') for your task. The description specifiy what one has to do to accomplish this task (e.g. *"Clarify, if and how this restricts the possibility of long-term preservation and re-use and if the rights onwer ist willing to grant the necessary rights."*). Both will be displayed in the project overview. + +Tasks depend on conditions. Each task must be linked to one or more conditions, and it will only be displayed if at least one of the conditions evaluates to true. + +![](../_static/img/how-to-guide/task_settings_general.png) +> *General task settings* + +#### Make a task date sensitive + +If your *Catalog* asks users to specify dates, e.g. start and end data of the project, you can use this information to schedule tasks in relation to the dates specified. + +With setting *Start date attribute* and *End data attribute* you can assign the related attributes of the questions. With *Days before* or *Days after* you can define in relation to the date stored in the attribute, when a task is visible. + +#### Select at least one Catalog + +The *Catalogs* field lets you choose the catalogs in which this task can be used. Not specifying a catalog and leaving the list empty implies that this task can be used with every catalog. + +![](../_static/img/how-to-guide/task_settings_date.png) +> *Date and Catalog task settings* + +### How to add a task to your catalog + +* Open the task settings +* Select your *Catalog* in the *Catalogs* setting at the bottom + +```{admonition} Info +If the *Catalogs* list is empty, the task is by default active for all catalogs. +``` + + + + + +## Glossary: Basics In this section, you will learn about the basic elements of RDMO to create your own questionnaire. To create a [*Catalog*](#catalog) in RDMO, you need to understand the hierarchical structure and the relationships between the different components. Here's a breakdown of how to build a [*Catalog*](#catalog) structure: @@ -602,7 +824,7 @@ In this section, you will learn about the basic elements of RDMO to create your ![](../_static/img/how-to-guide/icons.PNG) > *Icons* -With this icon set, which is available at the Catalog level, you can for example add elements or download your catalog. We explain them from the left to the right. The first icon will show you the content of your questionnaire in a nested or hierarchical view. The second icon, the pencil, activates the edit mode of the element. With the third icon you can copy/duplicate the complete catalog. With the fourth icon, the big plus, you can add additional elements like question or question sets. The switch (fifth) icon can disable or enable a catalog. A disabled catalog will not be available for the users. With the sixth icon (lock icon) you can lock or unlock the catalog. If a catalog is locked, it isn't possible to edit the catalog. If you want to download the whole catalog, you can do this with a click on the seventh, the export icon. +* With this icon set, which is available at the Catalog level, you can for example add elements or download your catalog. We explain them from the left to the right. The first icon will show you the content of your questionnaire in a nested or hierarchical view. The second icon, the pencil, activates the edit mode of the element. With the third icon you can copy/duplicate the complete catalog. With the fourth icon, the big plus, you can add additional elements like question or question sets. The switch (fifth) icon can disable or enable a catalog. A disabled catalog will not be available for the users. With the sixth icon (lock icon) you can lock or unlock the catalog. If a catalog is locked, it isn't possible to edit the catalog. If you want to download the whole catalog, you can do this with a click on the seventh, the export icon. ### Option sets @@ -622,69 +844,23 @@ Each of the three possible answers is an *Option* in RDMO. * You can reuse existing *Options* in new *Option sets* or create new ones. * An *Option* has a *Text* that is shown to the user (in our example above e.g. "I will not archive any data.") as well as a *Help* text and a so-called *View text*. The *View text* is only relevant for [*Views*](#views) and often missing in older *Options*. It determines what is displayed in RDMO views. -### Views - -Views can be used to select, arrange and format the answers or parts of the catalogue. Views are useful to reformat answers and to provide a streamlined, structured display of the answers. - -### Attributes - -* *Attributes* are at the heart of RDMO, linking content elements to project values. They play a crucial role in ensuring consistency and interoperability across different [*Catalogs*](#catalog) and RDMO instances. -* The answers given by a user are stored in this attribute and are not lost. This can be an advantage, as the answers will be displayed even if the user changes the catalog within a project created in RDMO. At the same time, however, there is a potential for danger: - * If you use a particular attribute for a certain question in the first catalog, but the same attribute for a different type of question in another catalog, the answers that were first entered by the user first will be retained, but may no longer make sense. If the user overwrites them in the second catalog, they will no longer make sense for the first catalog when they switch again. - -![](../_static/img/how-to-guide/wrong_attributes.PNG) -> *One Attribute for different Contexts* - - * The answers stored in the attributes are only exchanged within a project. If the user creates another project in which they answer a different catalog, no information is transferred. -* The RDMO domain contains 304 (01/25) hierarchically ordered attributes covering most aspects of RDM. -* The attributes are logically divided into three parts: - -1. URI Prefix: A character string structured as an URL. The default RDMO URI Prefix is the address of the institution, such as „https://your-institution.de/terms“. - -2. URI Path - -a) URI Path: The path provides information about the content of the question, with the scope being defined more and more concretely through the hierarchical structure. Separated by slashes, you work your way forward until you reach the “key”. As the name of the attribute should reflect the information expected when answering the question, the scope can be narrowed down. - -- For example, if you want to ask who is the project manager for a project, proceed from the general to the specific as follows: All in all, these are project-specific questions. So the top level of the path is the “project”. Then you want to get general information about its coordination, so you select “coordination” next. As you are looking for a person, the next level would be “name”. The full attribute is then “ https://rdmorganiser.github.io/terms/domain/project/coordination/name”. +### Tasks -b) URI Key: The key within the path is the last word, which is separated by a slash, and represents the most concrete level for identifying the question. +* Tasks display data management tasks which the user has to accomplish. -- The URI path can be very short, containing only a few terms, or it can be very long, depending on how many levels there are. It is advisable not to make the structures too specific so that the area does not become too small and the attributes can be better used. - -* When creating a catalog, each [*Question*](#questions) must use an attribute, which appears only once in it. -* [*Question sets*](#question-sets) can also be linked to an attribute as well. The default attribute here is "https://rdmorganiser.github.io/terms/domain/project/dataset/id". - * The use of attributes for Question sets does not affect the questions presented to users. Only when the „is collection“-Button is enabled can the user create „datasets“ when answering the catalog: - -![](../_static/img/how-to-guide/set.PNG) -> *Provide Datasets* - -* Overview of existing *Attributes* and usage: [Attribute Overview](https://rdmorganiser.github.io/terms/) - -#### Create New Attributes Sparingly: - -* How to Choose an *Attribute*: +### Views -There is no best practice on how to choose an attribute so far. If you’re not sure, please contact the RDMO group. +* Views can be used to select, arrange and format the answers or parts of the catalogue. Views are useful to reformat answers and to provide a streamlined, structured display of the answers. -* The steps you can take are the following: - * Review Existing *Attributes*: Familiarize yourself with the [RDMO domain](https://github.com/rdmorganiser/rdmo-catalog/blob/master-rdmo2.x/rdmorganiser/domain/attributes.xml), which contains 304 (01/2025) hierarchically ordered attributes. Identify the specific information your [*Question*](#questions) is trying to capture and look for *Attributes* that closely match your intent. *Attributes* in RDMO are organized in a tree-like structure, so navigate through the hierarchy to find the most relevant category. You can also have a look into [RDMO Terms](https://rdmorganiser.github.io/terms/) to find questions and their related attributes. - * Check *Attribute* Properties: Each *Attribute* has properties such as URI, key, and parent. Ensure these properties align with the context of your [*Question*](#questions). Example: The *Attribute* with the path `project/schedule/project_start` represents the start date of a project. The *Attribute* key is `project_start`. Its parent *Attribute* is the `project/schedule` *Attribute*, which itself is a sub-Attribute of `project`. When creating a [*Page*](#pages) [*Collection*](#collection), you should select the appropriate *Attribute*. ![Overview of available Attributes][image27] - -Cases where you'll need to create a new Attribute: +### Attributes -* Be sure that there is no matching attribute\! Even if the name of an attribute does not literally reflect the question, they are open enough to cover similar question content. For example, if you want to query when a campaign starts (instead of a project), you can still use the attribute “https://rdmorganiser.github.io/terms/domain/project/schedule/project_start” (if you have not already used it in the catalog), because you want to have similar pieces of information. - * Discipline-Specific Information: when capturing data unique to your field that isn’t covered by existing *Attributes*. Example: Specialized lab techniques or data formats or Institution-Specific Requirements: For information specific to your institution’s policies or processes. - * New RDM Aspects: - If addressing a new area of Research Data Management not currently in the existing *Attribute* set. - * If you have created a new attribute, the catalog is no longer so easy to reuse. When setting up an RDMO instance or a release, only the attributes that are in the domain are implemented - * You can contact the RDMO group and ask to include your attribute in the domain as well. - * You must provide the .xml including your attributes when sharing the catalog. The document describing the attributes has to be uploaded before the catalog. When sharing the “XML full” catalog, this remark is not relevant. +* *Attributes* are at the heart of RDMO, linking content elements to project values. They play a crucial role in ensuring consistency and interoperability across different [*Catalogs*](#catalog) and RDMO instances. You can learn more about them in the section [Understanding Attributes](#understanding-attributes). -## Future work +## How to contribute -In a next step, we will provide more detailed information on conditions, tasks and options. If you have any issues by reading and understanding or any wishes what also should be included here, feel free to make an issue or contact the rdmo group directly via [rdmo-contentgruppe@listserv.dfn.de](mailto:rdmo-contentgruppe@listserv.dfn.de). +If you have any issues by reading and understanding or any wishes what also should be included here, feel free to [create an issue](https://github.com/rdmorganiser/rdmo-docs/issues) or contact the rdmo group directly via [rdmo-contentgruppe@listserv.dfn.de](mailto:rdmo-contentgruppe@listserv.dfn.de). -### Authors +## Authors | Name | Mail | | :---- | :---- | @@ -694,6 +870,9 @@ In a next step, we will provide more detailed information on conditions, tasks a | Iven Fellhauer | [iven.fellhauer@urz.uni-heidelberg.de](mailto:iven.fellhauer@urz.uni-heidelberg.de) | | Stefan Gebhardt | [stefan.gebhardt@ub.uni-muenchen.de](mailto:stefan.gebhardt@ub.uni-muenchen.de) | | Marisabel Gonzalez-Ocanto | [ocanto@zbmed.de](mailto:ocanto@zbmed.de) | +| Laura Meier | [laura.meier@ub.uni-muenchen.de](mailto:laura.meier@ub.uni-muenchen.de) | | Jürgen Rohrwild | [juergen.rohrwild@fau.de](mailto:juergen.rohrwild@fau.de) | | Sabine Schönau | [schoenau@ub.rwth-aachen.de](mailto:schoenau@ub.rwth-aachen.de) | +| Janine Straka | [janine.straka@uni-potsdam.de](mailto:janine.straka@uni-potsdam.de) | | Kerstin Wedlich-Zachodin | [Kerstin.Wedlich@kit.edu](mailto:Kerstin.Wedlich@kit.edu) | +| Jürgen Windeck | [Juergen.Windeck@tu-darmstadt.de](mailto:Juergen.Windeck@tu-darmstadt.de) | \ No newline at end of file