In short
The catalog is Linkr’s shared shelf: projects, schemas, concept mappings and quality rules published by research teams. It is a directory of git repositories — each entry points at one, and installing it amounts to cloning it. Browsing works everywhere, including in the browser; installing needs server mode.
The badge refers to installing, which needs a server. Browsing the catalog works in both modes.
What it is for
A great deal of health-data work is redone identically from one institution to the next: describing a MIMIC database’s schema, mapping local codes onto a standard vocabulary, writing the quality checks for an OMOP warehouse. It takes time, and it is the same work everywhere.
The catalog answers that. One team publishes its schema, its rule set or its whole project to a git repository, declares that repository to the catalog, and the others install it in one click to start from there.
Two catalogs, not to be confused
The community catalog, described here, indexes Linkr entities to install. The data catalog documents a warehouse’s variables: what each field means, where it comes from. Neighbouring names, unrelated purposes.
Getting there
The catalog is a top-level sidebar entry, Catalog, next to Home and Workspaces. It belongs to no workspace: it is a resource of the whole installation.
On a first visit it does not load by itself. A Catalog not loaded screen invites you to click Load catalog, naming the server that will be contacted.
Why that explicit click
Loading the catalog contacts a server outside your institution. In a hospital setting an outbound request should never go out unless you decided it — hence the button rather than an automatic load.
Once loaded, the catalog is cached: it stays readable between sessions, with its update date. The Refresh button checks whether it has changed, and an Updates available banner summarises what is new, updated or removed.
Linkr can read several catalogs. The menu at the top right of the page picks the one you browse — the Community catalog by default, an institution’s catalog if you added one. Each keeps its own cache; the gear icon beside it opens their configuration (see Using an internal catalog).
Catalog
Browse and install projects, tools and mappings shared by research teams.
Want to share your own work? Open a merge request on interhop/linkr/linkr-catalog
Catalog not loaded
Load the community catalog to browse content published by research teams. This contacts framagit.org.
What you find there
Nine entity types can be published. Plugins are not among them: the catalog does not list them yet.
Workspace
A complete set, with its projects and resources. This is how the demonstration data arrives.
Project
A whole study: cohorts, dashboards, scripts.
Concept mapping
A correspondence between local codes and a standard vocabulary.
Script collection
Reusable SQL queries, organised in folders.
ETL pipeline
A transformation from a source model to a target model, OMOP for instance.
Data catalog
The documentation of a warehouse’s variables.
Quality rules
A set of checks to run against data.
Schema preset
A source’s description: its tables, its columns, how to read them.
Database
A public database and its data — the MIMIC-IV demo, for example.
Reading an entry
Each card opens with a coloured badge naming its type, then shows its name, version, description and tags; at the bottom, the author — hover it for the organization and dates —, the licence and the install button. The ⋯ menu offers Open repository, to inspect the content before installing, and Open in LinkR once the entry is installed. Clicking the card does one or the other depending on whether it is installed.
100 demo patients in OMOP format
Three states flag an entry to treat with care: Work in progress for unfinished work, Deprecated for a superseded entry, Unreachable when its repository no longer answers.
A red Requires Linkr 2.4.3 badge (for example) flags an entry published for a newer Linkr than yours. Its Install button is greyed out, and its tooltip says why: that entity type’s format changed in that version, and an older version would install it only partly, without saying so — a schema without its tables, for instance. Update Linkr to install it.
The same rule applies on import
Every recent export records the oldest Linkr able to read it. A ZIP or git repository imported into a version that is too old is refused before anything is written, with the same message: “This content needs Linkr 2.4.3 or later, and this instance runs 2.4.2…”. Nothing is half-imported.
The size is announced when it matters
Most entities weigh a few kilobytes of JSON. A database carries its data files — the MIMIC-IV demo is 18 MB — and the entry then shows it, to avoid the surprise on a slow connection.
Searching
A search bar and four filters: Type, Tags, Author and Organization. Sorting is the same as in Linkr’s other lists, and your choice is remembered.
The Organization filter does a particular service: it answers “what has that hospital published?”, which is often the real question when you are looking for content you can trust.
Installing an entry
The target workspace is chosen beforehand, in the selector to the right of the search bar. It is prefilled with the last workspace you opened, or the only one there is; it is also what decides which cards read Installed. A workspace-type entry does not need one: it creates its own workspace.
The Install button then clones the repository straight away, with no dialog in between; it reads Installing… while it runs. A window opens only if the item already exists, or if the install fails.
If you already have it, the card says so — Installed — and switches to Update when a newer version appears in the catalog; its tooltip recalls the installed version. Clicking either opens a window comparing the Installed version with the Catalog one before installing again.
Installing again replaces or duplicates
On an entry you already have, the application warns: “Already installed in this workspace. Installing again replaces or duplicates it.” As with an import, the call is yours — see Import and export.
An installed entity stays linked to its original repository. For the types that can pull — ETL pipelines, schemas, databases, mappings —, its fixes are then pulled from its Git repository panel, without reinstalling; for the others, Update installs it again. See Git versioning.
Installing a workspace: "Installed, but some content is missing"
A published workspace is made of pointers to each of its items’ repositories. They are fetched one by one, and some may fail — the common case being a private repository, which the install presents no credentials to.
The message then tells you exactly which ones stayed empty. The workspace is installed; what it lacks is the content of those items, which you can fetch afterwards by providing an access token.
Installing needs server mode
Installing clones a git repository, which the browser alone cannot do. In browser mode the catalog stays readable — you see the entries and can open their repositories — but the install button is unavailable.
To get published content into a browser-only installation anyway, download an archive from the repository and import it as a ZIP.
From the import window
The catalog also appears as the third tab of the Import window, From the catalog, filtered to the type you are importing. Handy when you already know what you are after: a schema, from the schemas page.
Using an internal catalog
The default catalog is public and open. An institution may prefer its own — for content that must not leave, or for a catalog validated internally.
Catalogs are managed from the Catalog page itself: the gear icon beside the catalog menu opens the Catalogs window. It offers:
- Add a catalog — a Name — typed in the interface language, like every multilingual name in Linkr: switch the application to the other language to translate it; untranslated, this name is shown —, the Catalog repository URL and its Branch. The catalog you add becomes the one shown.
- a row’s pencil, to rename it or point it at another repository;
- the bin, to remove it — the community catalog included. What you installed from it stays in place. A Restore the community catalog button brings it back.
Catalogs
The Git repositories you can browse from this page. Any GitLab instance works, for example a hospital's internal catalog.
Community catalog
https://framagit.org/interhop/linkr/linkr-catalog
Hospital catalog
https://gitlab.chu.example/entrepot/linkr-catalog
This list belongs to your browser, like the catalogs’ cache: each user builds their own.
What that address expects
An https URL to a GitLab repository — the public instance, a community forge, or your institution’s own GitLab. The index repository’s format is that of the public catalog, which can therefore serve as a model. Two catalogs cannot read the same repository.
When it does not work
The messages distinguish the causes, which saves you looking in the wrong place.
- Could not reach the catalog — no network, or an outbound connection blocked by the institution’s firewall. This is the most frequent case in a hospital.
- No catalog found at this address — the configured URL does not point at a catalog repository.
- No catalog configured — you removed them all: add one, or restore the community catalog, from the gear.
- The catalog file is not readable — the repository answers, but its content cannot be used.
- This catalog needs a newer version of Linkr — update the application.
Going further
- Publishing content — putting your own work there.
- Import and export — the two other ways to move an entity around.
- Database schemas — what gets installed most often from the catalog.
- Entities and sharing — what makes an entity installable.