79 lines
5.5 KiB
Markdown
79 lines
5.5 KiB
Markdown
---
|
|
title: Setup
|
|
weight: 10
|
|
---
|
|
|
|
This guide explains how to get started with the [knowledge pooling tool]({{% ref "/services/knowledge-pooling" %}}), 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:
|
|
|
|
- **[Contributors/Submitters](#setup-for-general-contributors-and-submitters):** Setup access to submit and view records
|
|
- **[Managers/Administrators](#setup-for-managers-and-administrators):** Configure authentication and permissions
|
|
|
|
## Overview of access and authentication
|
|
|
|
Access to the [knowledge pooling tool]({{% ref "/services/knowledge-pooling" %}}) 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]({{% ref "/services/knowledge-pooling" %}}), you must have read and write access to the `protected` collection of the pooling tool on the [TRR379 collaboration platform]({{% ref "/services/collaboration-platform" %}}).
|
|
You must be a member of both:
|
|
|
|
- [metadata-pool-read-protected](https://hub.trr379.de/org/q02/teams/metadata-pool-read-protected), and
|
|
- [metadata-pool-write-protected](https://hub.trr379.de/org/q02/teams/metadata-pool-write-protected).
|
|
|
|
To confirm your team memberships, first sign into the [TRR379 collaboration platform]({{% ref "/services/collaboration-platform" %}}) (see also [How to get a Hub account and log in]({{% ref "/howtos/hub-account" %}})), 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](#generate-a-personal-access-token).
|
|
|
|
#### Request access to `protected` team(s)
|
|
|
|
If you are *not* yet a member of the [metadata-pool-read-protected](https://hub.trr379.de/org/q02/teams/metadata-pool-read-protected) and/or [metadata-pool-write-protected](https://hub.trr379.de/org/q02/teams/metadata-pool-write-protected) team(s), please email [trr379@lists.fz-juelich.de](mailto:trr379@lists.fz-juelich.de?subject=Metadata%20pool%20protected%20teams) 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]({{% ref "/services/knowledge-pooling" %}}) requires a token linked to your Forgejo account.
|
|
|
|
#### Create a new token
|
|
|
|
From your [collaboration platform]({{% ref "/services/collaboration-platform" %}}) account, navigate to *[Profile and settings > Settings > Applications > Generate new token](https://hub.trr379.de/user/settings/applications)*.
|
|
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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
{{% notice style="accent" title="Important" icon="bolt" %}}
|
|
Treat your token like a password. Do *not* share it publicly.
|
|
{{% /notice %}}
|
|
|
|
#### 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]({{% ref "/howtos/pool-tool/general-usage" %}}) and [relevant workflows]({{% ref "/howtos/pool-tool/workflows" %}}) for instructions on how to enter or retrieve research metadata and outputs through the [knowledge pooling tool]({{% ref "/services/knowledge-pooling" %}}).
|
|
|
|
## Setup for managers and administrators
|
|
|
|
This section will describe how to configure the [knowledge pooling tool]({{% ref "/services/knowledge-pooling" %}}) from a management perspective, including:
|
|
|
|
- Defining **collections** (e.g., `protected`) and configuring the backend API (see also the [Dump Things Service documentation](https://github.com/christian-monch/dump-things-server/blob/master/README.md))
|
|
- Setting up and linking **Forgejo teams** for read and write access
|