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