Use the knowledge pooling tool

The knowledge pooling tool is a platform for collecting, curating, and sharing structured information about research activities, outputs, and contributors across TRR379 projects and institutions. It includes:

  • A web UI for submitting, editing, and browsing records such as people, projects, and publications
  • A backend API allowing scripts and applications to contribute or retrieve metadata
  • Token-based authentication that integrates with Forgejo teams on the collaboration platform to manage read and write permissions

The following workflows provide step-by-step guidance for working with the knowledge pooling tool:

Subsections of Use the knowledge pooling tool

Setup

This guide explains how to get started with the knowledge pooling tool, including how to access the system, authenticate as a contributor, and prepare for submitting or curating records. The focus of these steps differ depending on your role:

Overview of access and authentication

Access to the knowledge pooling tool is managed using tokens and Forgejo teams. Forgejo-based authentication ensures that permissions are linked to existing institutional or project accounts. Tokens are used to identify users with interacting with the API or web UI.

Each user can hold different roles, such as:

  • Submitter: Can create and modify records in their personal “inbox”.
  • Curator: Can view, edit, and approve submitted records.
  • Manager: Can configure access settings and team memberships.

Setup for general contributors and submitters

Collaboration hub access and permissions

To report and access records using the knowledge pooling tool, you must have read and write access to the protected collection of the pooling tool on the TRR379 collaboration platform. You must be a member of both:

To confirm your team memberships, first sign into the TRR379 collaboration platform (see also How to get a Hub account and log in), then click the links above to see the team members. If you are unable to see the repository, team member list, or if your username is not listed, see below how to request access. Otherwise, proceed to generate a personal access token.

Request access to protected team(s)

If you are not yet a member of the metadata-pool-read-protected and/or metadata-pool-write-protected team(s), please email trr379@lists.fz-juelich.de with a request to be added. Please send the email from an institutional email with the respective TRR379 project lead in CC.

Generate a personal access token

Reading and writing records into the knowledge pooling tool requires a token linked to your Forgejo account.

Create a new token

From your collaboration platform account, navigate to Profile and settings > Settings > Applications > Generate new token. Name the token, choose All for the repository and organization access, and click Select permissions to list further permissions; the token needs to have user:Read and organization:Read permissions. Click Generate token once all permissions are set.

User settings screen display for generating a token to grant access to your account using the Forgejo API. The Token name dump-things has been given. All (public, private, and limited) is selected for Repository and Organization Access. The remaining options are defined as follows: activitypub:No access, issue:No access, misc:No access, notification:No access, organization:Read, package:No access, repository:No access, user:Read. An orange Generate token button shows at the bottom. User settings screen display for generating a token to grant access to your account using the Forgejo API. The Token name dump-things has been given. All (public, private, and limited) is selected for Repository and Organization Access. The remaining options are defined as follows: activitypub:No access, issue:No access, misc:No access, notification:No access, organization:Read, package:No access, repository:No access, user:Read. An orange Generate token button shows at the bottom.

Copy the generated value and store your token securely; it will be used to authenticate your submission through the web UI and in API calls.

Important

Treat your token like a password. Do not share it publicly.

Test your token

You can verify that your token works using a simple API request:

curl 'https://pool.v0.trr379.de/api/protected/records/Thing' -H "x-dumpthings-token:<your-token-here>"

If the token is valid, this command will return a (potentially empty) list of entries. If the token is invalid, it will return an invalid token error, together with helpful information what may be wrong (e.g., wrong scopes).

Once your token is working and you have confirmed your access, you can proceed to the general usage guide and relevant workflows for instructions on how to enter or retrieve research metadata and outputs through the knowledge pooling tool.

Setup for managers and administrators

This section will describe how to configure the knowledge pooling tool from a management perspective, including:

  • Defining collections (e.g., protected) and configuring the backend API (see also the Dump Things Service documentation)
  • Setting up and linking Forgejo teams for read and write access

General usage guide

This guide explains how to use the knowledge pooling tool’s shacl-vue web UI and dump-things API service 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 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/.

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. 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.

Tip

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.

Authenticate with your access token

Submitting publication records will only be possible using a valid access token The token can be entered via the Key button in the web UI.

Screenshot showing token management button and pop-up window. Screenshot showing token management button and pop-up window.

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.

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 Screenshot showing the add-button for a publication record

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, or other metadata attributes.

Screenshot showing the edit-button for a publication record Screenshot showing the edit-button for a publication record

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 Screenshot showing where to hover to access the context help

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 Screenshot showing the item selector and constrained search

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

Tips for Searching
  • 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.

Save and submit records

Submitting metadata involves two different save actions: local saves and submitting to the server.

Save form sections (local save)

Important

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.

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 Screenshot showing the form save button

Submit to server

Once the record is complete and saved locally, 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, 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. Screenshot showing the form submit button, as well as the pop-up window prompting the user to enter their access token.

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. Screenshot showing the form submit button with a summary of the saved and to-be submitted record.

Possible errors

Authorization issues If the 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 Screenshot of the token prompt displaying an “invalid token” message

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. Screenshot of an empty publication record form with missing required fields highlighted.

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 Screenshot of the submission interface reporting an error

Workflows

The TRR379 knowledge pooling tool supports several metadata-driven workflows to collect and curate research information. Each workflow describes how contributors can create, edit, and/or review records for a specific type of research output or activity.

Before starting a workflow, see the setup and general usage guides for instructions on accessing the tool and working with the web interface and backend API.

Use the links below to learn more about individual workflows:

Subsections of Workflows

Publication reporting

The publication reporting workflow enables TRR379 members to register and curate metadata for publications associated with the consortium. This workflow ensures research outputs are accurately linked to relevant projects, topics, and contributors. Each submission includes contributor role assignments (e.g., author, senior author, etc.) to reflect the specific involvement of TRR379 members and collaborators.

In order to report a new publication, visit the knowledge pooling tool and select “Publication” as a data type from the left side of the page. Add a new publication by clicking the “plus” sign, or modify an existing record using its pencil icon.

Screenshot of the Publication page of the knowledge pooling tool Screenshot of the Publication page of the knowledge pooling tool

For publications to make the best impressions and live up to their fullest metadata potential, fill out the required and applicable optional fields. Where possible, the form lets you search through existing records, for example to easily link journals, authors, TRR topics, or projects.

Screenshot of the Journal search Screenshot of the Journal search Screenshot of the search listing available TRR topics Screenshot of the search listing available TRR topics

For fine-grained information, also select the contribution role a given co-author played - for example corresponding author or data manager.

Screenshots of a list of authors of a publication, with their contribution roles defined. Screenshots of a list of authors of a publication, with their contribution roles defined.

If non-TRR members authored or co-authored a publication, you can create new person records for these contributors. While TRR members can select trr-related prefixes for their persistent identifiers, external contributors can be identified persistently using, e.g., their ORCID.

Screenshot of the addition of a non-TRR member. The persistent identifier prefix is ORCID. Screenshot of the addition of a non-TRR member. The persistent identifier prefix is ORCID.

After saving, a well-curated publication record links to its authors, topics, and projects:

Screenshot of the Publication page with a saved by unsubmitted new publication record. Screenshot of the Publication page with a saved by unsubmitted new publication record.

Finally, submit the added or edited records using the “submit” button.

Screenshot of the Publication page, with the submission icon indication saved records that can be submitted. Screenshot of the Publication page, with the submission icon indication saved records that can be submitted.