Implementation Guide
1.2.0 - CI Build Implementation Guide - Local Development build (v1.2.0). See the Directory of published versions

How To Join

This section describes how to connect your biobank to the Sample Locator and what you need to have in place before you do so.


The Sample Locator is our central non-commercial and open source service, which enables scientists to search for specific research-relevant biosamples and related data across multiple academic biobanks distributed across Europe. Each biobank hosts a so-called Bridgehead, which connects to the central Sample Locator.

A Bridgehead comprises of two primary components:

  • The Blaze Store. This holds the actual data being searched. This store must be filled by you, generally by running an ETL on your locally stored data to turn it into the standardized FHIR format that we require.
  • Focus and Beam. These are the components that connect to the outside world. They collect the currently waiting queries from the Sample Locator, run them against the Blaze Store, and return aggregated results to the Sample Locator.

In order to make the data at your site searchable by the Sample Locator, you must install a Bridgehead at your site, fill the Store with data, and register Beam with the central Beam Broker.

More details about the functional principles of our IT infrastructure the can be found here.

The organization behind the development is the German Biobank Node in cooperation with BBMRI-ERIC, sponsored by the Federal Ministry of Education and Research.

General Requirements

  1. Installing and running a Bridgehead: All requirements for installing and running a Bridgehead are documented here.

  2. Data protection:
    Read this Data protection concept carefully and submit it to your data protection authorities. The data protection concept must be approved by your local data protection officer.

  3. Data access:
    To fill the Store of the Bridgehead you need access to clinical data from your local source systems. An overview about the clinical data which we want to provide in the ferderated search can be found here.

  4. Data format:
    The Store of the Bridgehead stores data as HL7 FHIR® Resources. To import data into the Store, they must be harmonised and converted. Each site must build an ETL-pipeline (extract, transform, load) to harmonise the structure of the data and translate them to fit predefined FHIR® profiles. You can find our FHIR® profile for the basic data set here and for the oncology data set here.

  5. Definition of “Sample”: A sample, as undestood by the Sample Locator, should satisfy the following conditions:

  • Samples for which all parameters are identical are considered to be a single sample and will counted only once - or- may only be loaded once into the store. &
  • Aliquots for which all must-support parameters from the profile are identical are considered to be a single sample and should be loaded only one in the store.
  1. Directory collections: The BBMRI Directory is a central resource that provides users standardized information about Biobanks in Europe. You will need to be registered with the Directory in order to be able to participate in the Sample Locator. If you run a biobank, you should be listed together with your collections in the Directory, a BBMRI-ERIC project that catalogs biobanks.

If possible, each sample that you wish to add to the Sample Locator should be assigned to a collection. Your collections should be registered with the Directory. Your ETL can be used to insert the relevant collection ID into each sample.

If this is not possible, then you should create or assign a single (default) collection specifically for use with the Locator. This collection should be registered with the Directory. Please let us know your default collection ID when you set up your Bridgehead.

A hybrid situation, where some of your samples have collections and some don’t, is also possible. In this case, you will also need to let us know your default collection ID.

Guides to install, fill and connect a Bridgehead

We provide a step-by-step installation guide on the Bridgehead GitHub page.

All of the components that make up the Bridgehead are open source. A complete list of our source code repositories can be found in the GitHub samply Repository.

FHIR® profiles and ETL:

  • The BBMRI FHIR® base profiles can be found here. The related Implementation Guide can be found here.

  • The FHIR® oncology profiles can be found here. The related Implementation Guide can be found here.

  • For implementing ETL, we recommend starting with the Reference Implementation.

  • Alternatively, an example of how to build an ETL-process with Talend Open Studio for Data Integration and Hapi FHIR API can be found here.

  • Instructions on how to validate your FHIR® resources can be found here.

Store documentations and tools:

  • The official Store documentation can be found here.

  • Specification for the REST interface used by the Store can be found here.

  • A standalone BBMRI FHIR® Test Data Generator can be found here.

  • A tool to control and fill your FHIR® Store from the Command Line can be found here.

Focus and Beam documentations and tools:

  • The official documentation can be found here and here.

Staying in contact

If you encounter problems or have further questions, you can contact us via the following email addresses:

  • For problems or questions regarding the GBA (Sample Locator) network, please send an email to:
  • For problems or questions regarding the BBMRI (Locator) network, please send an email to:

Reinforcing the team

Interested in developing and enhancing the Sample Locator components or our other open source software? Read our manifesto and join the Samply community!