docs.trr379.de/content/howtos/pool-tool/general-usage/index.md

---
title: General usage guide
weight: 20
---

This guide explains how to use the [knowledge pooling tool]({{% ref "/services/knowledge-pooling" %}})'s [`shacl-vue` web UI](https://pool.v0.trr379.de/ui/) and [`dump-things` API service](https://pool.v0.trr379.de/api/docs) to submit, edit, and review metadata records.
It applies to all record types, such as publications, personnel, projects, and topics.

For workflow-specific instructions (e.g., publication reporting), see the [Workflows]({{% ref "/howtos/pool-tool/workflows" %}}) section.

## Submit or edit a publication record using the web UI

The web UI for submitting, editing, and browsing records is provided at [https://pool.v0.trr379.de/](https://pool.v0.trr379.de/).

![Screenshot of https://pool.v0.trr379.de/. The page is titled, TRR379 Research Metadata System and subtitled, User interface and API for pooling information across project sites and consortium partners. The ACCESS LATEST EDITOR VERSION button is circled in red with a red arrow pointing to it. There is an About paragraph that describes the metadata pooling service as follows: This is the metadata pooling service of TRR379. It is designed to be used by consortium partners to report on data collections and other research activities, in order to communicate them to the consortium at large. Meta data records can be submitted by authorized users and automated processes. Records are stored on a secure server at Forschungszentrum Jülich. Individual record types are classified to either be publicly accessible, or to be available to particular users via authenticated requests only. The TRR379 Q02 project develops and operates this service. Underneath the About paragraph, is a Components section with three components: Editor, API, and Schema. The TRR379 logo is displayed at the top right of the screen.](knowledge-pooling-tool.webp)

{{% notice style="primary" title="Tip" icon="lightbulb" %}}
It is **highly recommended** to use this web UI with a desktop browser;
the form offers rich contextual information that is hard to access on mobile devices.
{{% /notice %}}

### Authenticate with your access token

Submitting publication records will only be possible using a valid [access token]({{% ref "/howtos/pool-tool/setup/index.md#generate-a-personal-access-token" %}})
The token can be entered via the Key button in the web UI.

![Screenshot showing token management button and pop-up window.](enter-token.webp)

### Create or edit a record

Records correspond to structured metadata entities (e.g., Person, Topic, Publication).
Each record is created and managed through a form defined by the [metadata schema](https://concepts.trr379.de/s/research-assets/unreleased/).

If no record on a given entity already exists, a new record must be created.
Click the `+` (plus) button next to the desired record type (e.g., Publication or Person).

![Screenshot showing the add-button for a publication record](create-record.webp)

Alternatively, if a previous record already exists, it can be loaded by clicking on the Edit button (pencil icon).
You can search for records by title/name, [identifier]({{% ref "/resources/identifier-concept" %}}), or other metadata attributes.

![Screenshot showing the edit-button for a publication record](edit-record.webp)

### Fill out record fields

Context help describing expected values and controlled vocabularies is provided for each field.
Hover your mouse pointer over the field label to display help text.

![Screenshot showing where to hover to access the context help](context-help.webp)

For some fields (e.g., authors or publication venue when filling out a publication record), one or more choices have to be selected.
The selector offers type-ahead search of choices.
The selection is contrained to choices matching the entered text in their label.
Select the appropriate value from the dropdown list.

![Screenshot showing the item selector and constrained search](selector.webp)

If no adequate choice exists, click *Add New Item* to create one.

{{% notice style="primary" title="Tips for Searching" icon="lightbulb" %}}
- Try entering full names instead of abbreviations
- If an item is not found in one language, try searching its English version
- Wait a few seconds for choices to populate before creating a new record; search results may take time to load.
{{% /notice %}}

### Save and submit records

Submitting metadata involves two different save actions: [local saves](#save-form-sections-local-save) and [submitting to the server](#submit-to-server).

#### Save form sections (local save)

{{% notice style="accent" title="Important" icon="bolt" %}}
**Saving only stores the information in the local browser session!**
It does not submit the record to the server to make it visible to curators.
{{% /notice %}}

Whenever a record (or sub-field) is completed, it must be saved by clicking the *Save* button.
**You must do this for each section you complete.**
Saving temporarily stores the record in your browser session.

![Screenshot showing the form save button](save-form.webp)

#### Submit to server

Once the record is complete and [saved locally](#save-form-sections-local-save), it can be submitted to the server by clicking the *Submit* button (cloud icon with up arrow), which will show a green indicator if changes have *not* yet been submitted to the server.
If you haven't already [entered your access token](#authenticate-with-your-access-token), the interface will prompt you to do so.

![Screenshot showing the form submit button, as well as the pop-up window prompting the user to enter their access token.](submit-form.webp)

The interface will provide you with an overview of the changes you are about to submit.

![Screenshot showing the form submit button with a summary of the saved and to-be submitted record.](submit-overview.webp)


#### Possible errors

**Authorization issues**
If the [access token]({{% ref "/howtos/pool-tool/setup/index.md#generate-a-personal-access-token" %}}) you are providing is incorrect or does not have appropriate permissions, the interface will display an error like this during metadata retrieval or submission:

![Screenshot of the token prompt displaying an "invalid token" message](invalid-token.webp)

**Incomplete information**
If a metadata record is missing required information, you will not be able to save it.
Required fields - highlighted with a red asterix - and an warning sign will alert you to this.

![Screenshot of an empty publication record form with missing required fields highlighted.](incomplete-form.webp)

**Internal errors**
If there is an unexpected error during metadata submission, the submission interface will report technical information.
Please contact m.hanke@fz-juelich.de and copy the entire error message.

![Screenshot of the submission interface reporting an error](submit-error.webp)