# DATA HUB User Guide

This guide applies to **DATA HUB 1.1.6**.

API documentation is available from a running DATA HUB backend at [`/api/docs`](/api/docs). The public deployment also exposes the same interactive OpenAPI reference at <https://datahub.tools.rpdm.rwth-aachen.de/api/docs>, and the raw OpenAPI document at [`/api/openapi.json`](/api/openapi.json).

The DATA HUB helps you find, inspect, compare, and reuse research data products. It connects data products with projects, people, publications, quality signals, and cross-project imports.

Keyword fields offer optional terms from the current project's keyword catalogue only; keywords from other projects are never mixed into the suggestions. Each suggestion includes a usage summary; hover or focus it to see a capped list of matching items. Selecting a suggestion adds it as a removable keyword pill, while Enter or a comma turns a manually entered term into the same kind of pill. Capitalization and common singular/plural variants are grouped without bulk-rewriting existing source records.

## Normal User

### 1. Open a project

Open the DATA HUB start page and choose a project from the list. You can also paste the full project ID into the project field if someone gave you one.

Or navigate directly to your project:

```text
https://datahub.tools.rpdm.rwth-aachen.de/?conf=<project>
```

Examples:

```text
https://datahub.tools.rpdm.rwth-aachen.de/?conf=demo-1234
https://datahub.tools.rpdm.rwth-aachen.de/?conf=demo-engineering-1234
```

Use the start page when you want to switch projects. Use a direct project link when you already know where you want to go.

### 2. Choose the right view

The compact project navigation in the toolbar lets you jump directly between `Domain`, `Data Product`, `Hub`, and `Governance`, matching the four tiles on the project start page. Use `Main page` to return to those four large tiles.

Use `Data Products` when you want to browse the available data products as cards. This is the best view for finding, comparing, and opening products.

Use `Overview` when you want to understand the whole project: coverage, projects, people, publications, governance, lifecycle, and reuse signals.

The badge next to `User guide` shows the approximate number of active browser sessions for the currently opened project.

### 3. Search effectively

The global search bar searches across data products, projects, persons, publications, keywords, standards, descriptions, DOI values, registry IDs, and linked context.

Start broad, then narrow down:

- Search a plain word such as `coastal`, `sensor`, `battery`, `simulation`, or a person's name.
- Search a phrase from a title or description.
- Search an identifier such as a registry ID, DOI, BibTeX key, ORCID, project code, or product ID.
- Use `field:value` searches when you know what kind of result you want.

Useful searches:

- `product:shared` shows data products that the current project shares with other projects.
- `product:imported` shows data products imported from another project.
- `area:A` shows items connected to project area A.
- `status:active` shows active projects, people, or products where that status is registered.
- `domain:coastal` shows products in a matching domain.
- `project:demo` shows items linked to a project whose ID, code, name, area, or status contains `demo`.
- `projectName:Coastal Resilience Demo` searches by project name.
- `person:Rivera` shows items connected to a person matching that name.
- `publication:climate` shows items connected to matching publications.
- `doi:10.` searches DOI values.
- `key:smith2024` or `bibtexKey:smith2024` searches publication keys.
- `registryId:dp-` searches product registry IDs.
- `name:temperature` searches item names when a name field exists.

Search tips:

- Search is case-insensitive.
- A plain search is often best when you are unsure which field contains the term.
- A scoped search such as `area:A` only works when that field exists for the item.
- Click area, keyword, or standard chips when you want to reuse an existing filter.
- Use `Clear` to reset the search and filters.

### 4. Build project queries in the UI

Use `Overview` and open `Query` when you need a count or table across linked project metadata. The Query workbench can answer questions that are broader than the normal search bar, such as which projects have linked publications, which products have owners, or which imported products still need local context.

Start with the `Builder` tab. It is the normal UI path and does not require writing query text.

1. Choose an `Entity`.
   This decides what each result row represents: data products, projects, people, or publications.

2. Choose `Properties`.
   These become the result columns. Properties are grouped like the detail views, so metadata, linked items, governance, provenance, import, and sharing fields are easier to find. The result table uses the same labels you selected. Columns are optional display fields: selecting a column should not remove an otherwise matching row when that metadata is missing.

3. Add `Conditions` when you want to narrow the result.
   Use `+` to add another condition row. Each condition has a field, an operator, and usually a value. The field dropdown includes a filter box, which is useful when the list is long. Conditions are the part of the Builder that filters rows.

4. Run the query.
   Use `Run query`. The result area shows a table, a count, or a message if no rows matched.

5. Open results directly.
   Many result cells are clickable. Project cells open project details, person cells open person details, data product cells open data product details, publication cells open publication details, and keyword cells open the keyword detail view.

Useful Builder controls:

- `All` selects every available column for the chosen entity.
- `Clear` removes selected columns and leaves only the entity identifier.
- `Start over` resets the Builder to a blank data-product query.
- `API result` changes the output shape when you copy the query for technical reuse.
- `Copy API call` copies the current Builder query for developers or scripts.

Common UI workflows:

- Find open data products: choose `Data products`, select `Name`, `Access`, `Status`, and `Owner name`, then add condition `Access` `is` `Open`.
- Review controlled data: choose `Data products`, select `Name`, `Access`, `Access procedure`, `Legal basis`, and `Owner name`, then add condition `Access` `is` `Controlled`.
- Check products with missing review context: choose `Data products`, select `Name`, `Validation status`, `Next review due`, and `Data steward`, then filter for the review status you need.
- Find products with sample or record counts: choose `Data products`, select `Name`, `Samples / records`, and `Owner name`, then add condition `Samples / records` `exists`.
- Review imported products: choose `Data products`, select `Name`, `Imported`, `Import source`, `Source product ID`, and `Local import context`, then add condition `Imported` `is` `true`.
- Find active projects and their team members: choose `Projects`, select `Name`, `Area`, `Status`, and `Team member`, then add condition `Status` `is` `active`.
- Find subprojects: choose `Projects`, select `Name`, `Area`, and any linked columns you want to inspect, then add condition `Keywords` `is` `subproject`.
- Find subproject pilots: choose `Projects`, select `Name` and `Area`, then add two conditions: `Keywords` `is` `subproject` and `Keywords` `is` `pilot`.
- Look up publications by project context: choose `Projects`, select `Name` and `Publication key`, then add condition `Publication key` `exists`.
- Count people with publication links: choose `People`, select `Name`, add condition `Publication key` `exists`, then use `API result` set to `Count only` if you need only the number.

Use the `Editor` tab only when you need to inspect or manually adjust the generated query. Most users can stay in `Builder`; the Editor is mainly for technical users who already know the query syntax.

The `Preconfigured query` dropdown loads reusable examples directly into the Editor, including the shared-data-product project relationship query. Project editors can use `Save current` to give the current query a name and store it with the project. Stored project queries appear for everyone who can open that project. Select a stored project query and use `Delete saved` to remove it; built-in queries cannot be deleted.

#### Project relationships through shared data products

Use this query to list project pairs that are connected through at least one shared linked data product. The final filter removes self-pairs and duplicate reverse directions.

```sparql
PREFIX datahub: <https://datahub.local/vocab#>
SELECT ?projectAId ?projectAName ?projectBId ?projectBName ?productId ?productName
WHERE {
  ?projectA a datahub:Project .
  ?projectA datahub:id ?projectAId .
  ?projectA datahub:name ?projectAName .
  ?projectA datahub:hasDataProduct ?product .

  ?projectB a datahub:Project .
  ?projectB datahub:id ?projectBId .
  ?projectB datahub:name ?projectBName .
  ?projectB datahub:hasDataProduct ?product .

  ?product datahub:id ?productId .
  ?product datahub:name ?productName .

  FILTER(STR(?projectAId) < STR(?projectBId)) .
}
```

#### Project kinds and subprojects

Project kinds such as `official project`, `subproject`, `platform`, `service`, `associated activity`, and `external collaboration` are modeled as project keywords. They are not separate project type fields. This keeps project categorization searchable, exportable, and queryable with the same keyword mechanism used elsewhere in DATA HUB.

Use one keyword condition to find all projects with a kind:

```sparql
PREFIX datahub: <https://datahub.local/vocab#>
SELECT ?project ?name ?area
WHERE {
  ?project a datahub:Project .
  ?project datahub:keyword "subproject" .
  OPTIONAL { ?project datahub:name ?name . }
  OPTIONAL { ?project datahub:area ?area . }
}
```

Use repeated keyword conditions when every listed keyword must be present:

```sparql
PREFIX datahub: <https://datahub.local/vocab#>
SELECT ?project ?name ?area
WHERE {
  ?project a datahub:Project .
  ?project datahub:keyword "subproject" .
  ?project datahub:keyword "pilot" .
  OPTIONAL { ?project datahub:name ?name . }
  OPTIONAL { ?project datahub:area ?area . }
}
```

### 5. Read a data product card

A data product card gives you a compact decision view. Look for:

- the product name and registry ID
- domain, status, lifecycle, and update information
- keywords and standards
- linked projects, people, and publications
- completeness and governance signals
- `IMPORTED DATA PRODUCT` or `SHARED DATA PRODUCT` badges

Open the card when you need the full detail view.

### 6. Inspect item details

The detail view explains what an item is and how it connects to the rest of the project.

For a data product, check:

- what the product contains
- who owns or curates it
- where it is registered or stored
- which project uses it
- which publications mention it
- whether it is imported or shared
- what local context was added in the current project

For projects, people, and publications, use the linked-item sections to move through the network.

For project detail views, `Related projects via data products` shows other projects that are connected through at least one shared linked data product. Each row names the related project and lists the shared data products that create the relationship.

The detail view is organized into sections with navigation buttons at the top. Use those buttons to jump between metadata, linked items, calculated indicators, data mesh, version history, and other sections when available.

In copied direct item links, navigation to other items is intentionally disabled. Links in `Identifiers and locations` remain clickable, the data mesh can still be inspected, and `Report issue` remains available.

### 7. Understand imported and shared products

`IMPORTED DATA PRODUCT` means the product comes from another project. The source metadata is read-only in the importing project. The importing project may add local context and local links so the product makes sense in the local project.

`SHARED DATA PRODUCT` means the product is exposed by the current project for one or more allowed importing projects.

The source project remains responsible for the authoritative product metadata.

### 8. Copy a direct link

Use `Copy public link` in a detail view when you want to send someone directly to one exact item without exposing the project configuration ID.

The copied link:

- opens the selected item directly
- is read-only
- does not give edit access
- disables navigation to other items
- hides metadata coverage percentages and calculated score explanations
- still allows the receiver to report a metadata issue
- keeps external identifier and location links clickable
- does not require the receiver to search for the item again
- is useful in emails, tickets, documentation, reports, and chat messages

Use `Copy internal-only link` when another authorized internal user should open the item inside the full project portal. This link contains the project configuration ID, keeps normal portal navigation available, and does not grant edit access. Treat it as an internal reference and do not publish it. After the item opens, the project and item parameters are removed from the address bar; refreshing then opens the project normally instead of reopening that item.

Editors can also find the project's `Configuration ID` and `Configuration path` in the `Reference` section of `Edit Project`. These values identify the project but do not grant edit access.

### 9. Report a metadata issue

If you notice unclear, incomplete, outdated, or wrong metadata in a data product detail view, use `Report issue`.

Enter your name so admins know who reported the issue. You may also add an email address if admins should be able to contact you. The email address is optional.

Use the report message to describe what should be checked. For example:

- the access procedure is unclear
- a contact person seems outdated
- a keyword or standard is missing
- the lifecycle or status does not match the product description
- a link to a project, person, or publication looks wrong

The report is saved for the project admins and stays linked to the affected data product. Reporting an issue does not change the metadata itself and does not require edit access, including from copied direct item links.

After saving, the DATA HUB shows a report ID such as `report-...`. Keep this ID if you want to refer to the report later. The report form can also be submitted with `Cmd+Enter` on macOS or `Ctrl+Enter` on Windows/Linux.

### 10. Use the information

The DATA HUB is meant to help you answer practical reuse questions:

- Is this the right product for my task?
- Is it current enough?
- Which project owns it?
- Who should I contact?
- Which publication or project explains it best?
- Is there a shared or imported version elsewhere?
- Are there related products I should inspect?

Normal users can view and inspect content. Creating new items, editing metadata, and saving local overlays are project-admin tasks.

## Project Admin

### 1. Access and editing

Project write access allows editing one project.

The browser stores supplied access locally. If the DATA HUB shows `No browser write token`, click that status and paste the project write token.

### 2. Edit project settings

Use `Edit` in the toolbar to manage:

- portal title, subtitle, description, contact, and data version
- branding assets and colors
- publication source
- feature flags and read-only mode
- write tokens
- federation audience ID
- imported source audiences

The Activity section appears only when backend admin access is present.

### 3. Edit project content

Use `New` to create new metadata entries. Use `Edit Item` in a detail view to update an existing item.

Admins can edit:

- project metadata and links
- person metadata and links
- publication links
- data product metadata, governance, provenance, access, and links
- local context and local links for imported data products

Data product lifecycle uses the stages `Draft`, `Registered`, `Curated`, `Validated`, `Published`, and `Deprecated`.

#### Delete and restore local items

Project admins can soft-delete local data products, projects, and people. Publications cannot be deleted from the portal; admins can edit publication metadata and links, but publication records remain part of the active bibliography-backed collection.

Deletion requires project admin access. A regular browser write token can save editable project content, but the deleted-items archive and restore controls are only shown after admin access is active.

To delete an item:

- open the item detail view
- choose `Edit Item`
- use `Delete` next to `Save`
- enter the required deletion reason in the Data Hub dialog
- confirm the deletion

After confirmation, the item is removed from active project pages, cards, filters, query results, and normal links. The retained record is stored centrally in the admin-only `deletedItems` archive with:

- item type and item ID
- deletion time
- deletion reason
- admin token information for the actor
- the retained item payload
- the links removed from the active graph

To review deleted items, open Project settings and use the `Deleted items` section. This section is only accessible for project admins. Each row shows the deleted item type, ID, deletion time, link count, and reason.

Use `Open` to inspect a deleted item. The opened view behaves like a detail view, but it is inactive: it does not navigate through active portal content and it does not allow normal item editing. The deletion reason is shown prominently at the top so the audit context is visible before the retained metadata. The view also includes deletion metadata and the retained item/link payloads for inspection.

Use `Restore` from the deleted-items row or the inactive detail view to restore an item. Data Hub asks for confirmation before restoring. If no active item with the same ID exists, the item and its retained links are restored and the deleted-items entry is removed from the archive. If an active item with the same ID already exists, the restore is rejected and the project data is left unchanged.

Normal project JSON responses and public project views do not expose the deleted-items archive. Admins load it through the Project settings workflow.

Imported product source metadata remains read-only. Local overlays belong to the importing project.

When creating links in `New`, first fill the `Relation` or `Role` field and the `Confidence` field. Then choose the two linked items from the filterable selectors below. On wide screens the two selectors are shown side by side; long selector lists show the first items and scroll internally. Hover the `?` marker on a selectable item card to see more information before selecting it.

New projects can be linked to persons, data products, and publications during creation.

### 4. Configure federation

Federation is audience-based.

The importing project has an audience ID. The source project allows that audience ID on individual data products. When the audience matches, the importing project can show those products automatically.

To check missing imports:

- confirm the importing project's audience ID
- confirm the source product allows that audience ID
- confirm the source project is available to the backend
- search `product:imported` after saving settings

### 5. Review activity and versions

Use Activity to understand recent project changes. Use data product version history to inspect previous states or restore a product when needed.

If a save is rejected because someone else changed the project first, reload the page, review the current state, and then save again.

### 6. Review metadata reports

Open reports appear in `Maintenance` under `Metadata report inbox`. The inbox starts as a compact summary with counts for open, resolved, and total reports.

Click a count to show the matching reports:

- `open reports` shows reports that still need attention
- `resolved reports` shows reports that were already handled
- `total reports` shows the full report history

Each report shows the reporter contact details, links back to the affected data product, and contains the user's message. Admins can open the item, edit the metadata when needed, and mark the report as resolved. If a report was closed too early, it can be reopened.

Each report has a report ID. Use the search field inside the `Metadata report inbox` to find a report by ID, product, reporter, or message. This search only filters the admin report inbox and does not change the main project search.

Use resolved reports as a lightweight audit trail. They stay collapsed by default so they do not take space during normal curation work.

### 7. Troubleshooting

If a project does not load, check that the project ID is correct and includes the salt.

If imported products are missing, check the audience IDs on both sides.

If overlay edits do not save, check whether the browser has a valid write token or admin token for the importing project.

If the token prompt rejects an admin token on localhost, make sure you are running the DATA HUB backend, not a static file server.

If you see `database is locked`, retry after a short wait. If it persists, restart the app service so stuck SQLite connections are closed.