Merge branch 'dmp-refactoring' of https://code-repo.d4science.org/MaDgiK-CITE/argos into dmp-refactoring

docs/docs/documentation/administration/notification-templates.md

@@ -48,7 +48,7 @@ You can also clear any filters already applied, by pressing the `clear all filte
 
 ## Edit form
 
-When you try to add new notification templates or edit existing ones, the **notification template editing form** will appear containing the following controls:
+When you try to add new notification templates or edit existing ones, the **notification template editing form** will appear containing the following sections.
 
 ### Main information section
 

docs/docs/documentation/administration/reference-types.md

@@ -1,5 +1,137 @@
 ---
 sidebar_position: 5
+description: Manage all reference types
 ---
 
-# Reference Types
+# Reference Types
+
+In this page, there is a listing where you can view details about all the available reference types.
+
+:::info
+
+A **reference type** is any type of information that is made available to the users when they fill [plan](/docs/category/plans) forms. This information is either static, or coming from an outside source (*an external API*). These sources are extremely configurable as we will see in this section.
+
+:::
+
+The information displayed by default is: the `name`, the `status`, the `identification code` and timestamps for the `creation` and `updates` of the records. At the top right corner of the listing you can also select which columns to display.
+
+:::tip
+
+For reference types, all the columns are visible by default.
+
+:::
+
+You can also create new or edit / remove reference types by clicking to the `+ Create Reference Type` button at the top right of the page or to the three dots at the last column, respectively.
+
+## Authorization
+
+Only users that have the **Admin** role can access this page.
+
+## Pagination
+
+Not all the records are being displayed at once. By default, there is a pagination of 10 records applied to them.
+
+You can control how many records are being displayed at any time, by adjusting the `items per page` control at the bottom left corner of the table.
+
+## Filtering
+
+There is a filtering option available for reference types.
+
+- **Is Active**: By toggling this control you can view only the active or only the disabled reference types.<br/>*By default, this option is set to true.*
+
+In order for the filters to apply, you have to click the `Apply filters` button. 
+
+You can also clear any filters already applied, by pressing the `clear all filters` option, located at the top of the popup.
+
+## Edit form
+
+When you try to add new reference types or edit existing ones, the **reference type editing form** will appear containing the following sections.
+
+### Main information section
+
+- **Name**: The label of this reference type.
+- **Code**: The identification code which is used internally for this type. 
+
+### Fields section
+
+In this section we can add custom fields made available from the source. When the `Add Field` button is pressed, a form appears containing the following controls:
+
+- **Label**: The label of the field.
+- **Description**: A short description for the field. <br/>*This is optional*
+- **Code**: An identification code for this field, used for the information mappings we will discuss about shortly.
+- **Data Type**: The data type of a field information can either be `Text` or `Date`.
+
+:::tip
+
+There is no limit on the fields that can be configured. To remove a field configuration, press the `delete` icon on the right side of the field form.
+
+:::
+
+### Sources section
+
+In this section we can add configuration for the sources of this reference type. The configured sources can be more than one. This is useful when there is a need to 'merge' information coming from multiple sources at the same time. The basic information we can provide for a source is the following:
+
+- **Key**: An identification key for our source.<br/>*Used internally by the system.*
+- **Label**: A display name for our source.
+- **Ordinal**: This specifies the order in which the source will be called.
+- **Dependencies**: A source can be dependent on other reference types. Here we can specify these dependencies.
+- **Source Type**: It can either be `API` or `Static`.
+
+:::info
+
+All the options that follow are only applicable if the source type we select is `API`. In case we select `Static` the only thing we can add are the static fields of the source and their values.
+
+:::
+
+- **Url**: The url of our source.
+- **Pagination Path**: The path inside the response in which the pagination information is located. This is only needed if the results are coming paginated from the source.
+- **Content Type**: The content type of the responses of the source.<br/>*In most cases, this is `application/json`.*
+- **First Page**: We can specify the first page to be different than the default 0.
+- **HTTP Method**: The http method the source expects. This can either be `GET` or `POST`.
+- **Filter Type**: How filtering is handled when this source is used. This can be set as `local` or `remote`.<br/>*In most cases, this is `remote`, meaning that the source handles the filtering. If set to `null`, the filtering (if any) is also handled remotely by the source.*
+- **Results**: The path inside the source response where the results are located.
+
+### Mappings section
+
+In this section we can specify how we will be consuming the information coming from our sources by mapping all the source fields we are interested in.
+
+For every field we have to specify the response path on which the information resides.
+
+By default, there are three fields available for mapping from the start. 
+
+- **reference_id**: This can be used for identifier fields
+- **label**
+- **description**
+
+If we have specified more fields for our source, these will also appear by their code in this form for configuring their paths.
+
+### Authentication section
+
+Some APIs require authentication. In this section we can specify the information about how our source API handles authentication. It is optional, and the form can be enabled by checking the `Authentication` checkbox. The options we have are the following:
+
+- **Url**: The url where the API listens for authentication.
+- **HTTP Method**: The HTTP method for the authentication request.
+- **Token Path**: The path of the token, concatinated after the token type. <br/>*In most cases, it is `null`.*
+- **Type**: The token type.<br/>*In most cases, it is `Bearer`.*
+- **Request Body**: The body contents of the request, if required.
+
+### Queries section
+
+In this section we can specify query parameters we can apply to our requests.
+
+- Name: The name of the query parameter. <br/>*For example, `like`.*
+- Default Value: The default value of the parameter.<br/>*This is optional.*
+
+## End notes
+
+:::tip
+
+The path fields on this form are using the [JsonPath](https://github.com/json-path/JsonPath) format.
+
+:::
+
+:::note
+
+For every source we add, the form gets populated with new `field mapping`, `authentication` and `queries` sections we can configure as we saw above.
+
+:::