BioMedIT Portal User Guide

• 1: Login
• 2: Home
• 3: Profile
• 4: Groups
• 5: Projects
• 6: Data Transfers
• 7: Contact Us
• 8: Central Services
• 8.1: DCC GIT
• 8.2: Harbor

In the following sections we introduce the BioMedIT portal, how it works and how to get started using it.
Please use the table of contents menu to the left or below to navigate the topics.

What is the BioMedIT Portal?

The BioMedIT Portal is the one-stop entry to the BioMedIT Network. It provides users with a single point of access to the tools and services of the BioMedIT Network in a secure web-based environment.

With the Portal:

• Project Leads have a consolidated view of their projects and resources, enabling them to manage the research team’s members and access the project space.
• Data Providers and Data Managers oversee data transfers and monitor them.
• Researchers gain access to an expanding collection of collaborative and research-oriented tools, which encompass in-house, commercial, and open-source resources.

Access is secured with a login with your SWITCH edu-ID account and two-factor authentication.

Table of Contents

1 - Login

To either register for the first time or login to the BioMedIT portal:

1. Go to: https://portal.dcc.sib.swiss/. The SWITCH edu-ID authentication button will appear.
2. Click on > SWITCH edu-ID.
3. Enter your email address and click on Continue. You will be asked to enter your password.
4. Your second authentication method prompt will appear (SMS, OTP). Enter your Code and click on Login.
5. You will be asked to:
   1. Enter a username of your choice.
   2. Choose which of the emails associated to your SWITCH edu-ID account to use for the BioMedIT Portal.
   3. Agree with the Portal being notified when your affiliation changes.
   4. Agree with the BioMedIT Portal Private Policy.
6. The BioMedIT Portal Home will be displayed.

2 - Home

As soon as you log in with your SWITCH edu-ID, the home page displays the menu bar of the left side, the Quick Access Panel, with short-cuts to central services in the middle, and the BioMedIT Feed on the right, where you may find news and announcements from the BioMedIT Team.

The Portal classifies user accounts by role, and the menu options visible for each user will depend on the role assigned. A Data Provider, a Project Leader, or a visitor without a specific role will all see different default menu options

Quick Access links

• SPHN Schema Forge
• SPHN DCC Confluence
• Terminology Service
• GitLab
• Harbor

3 - Profile

From the profile menu option, users can check and update their account details, and manage their OpenPGP Keys and SSH Keys.

My Profile tab

The My Profile tab shows the user’s account details.

Account details:

• Name: User’s name

• Username: User SWITCH edu-id identifier

• Local Username: The username the user chose during their first login to Portal.

• Email: Contact email currently selected from the list retrieved from the user’s SWITCH edu-ID

• Affiliations: List of organizations (e.g., university, research institute) linked to users SWITCH edu-ID account

• IP Address: The IP address from where the user is connecting

• Flags: List of flags enabled for the user

• Groups: The list of Groups the user is a member of.

Note that personal details are retrieved from the user’s SWITCH edu-ID. For any changes to their personal data or affiliated organizations, user may update their SWITCH edu-ID via this link.

For more resources about SWITCH edu-ID, refer to SWITCH edu-ID / Quick Links.

OpenPGP Keys

From the OpenPGP Keys tab, users can see the PGP Keys they have registered in the Portal, along with their status.

Each key has the following information:

• Fingerprint: This is a unique identified for each PGP key. You should make sure sure that this value is matching with the fingerprint of your key.

• User ID: User ID associated with the PGP key. People usually have their full name (and sometimes affiliation) in this field.

• Email: Email address associated with the PGP key

• Status: The approval status of your key. The list of key statuses is as follows:

  • PENDING: a key approval request was submitted, but the key has not been approved yet. This is a manual process and can take from a few hours or up couple of days.
  • APPROVED: key is approved for usage within the BioMedIT network. Only approved keys can be used to encrypt, sign and decrypt data packages that are transiting via the BioMedIT network.
  • APPROVAL-REVOKED: approval of the key has been revoked by the BioMedIT key validation authority.
  • KEY-REVOKED: key has been revoked by its owner.
  • REJECTED: key is not trusted by the BioMedIT key validation authority.
  • DELETED: key has been removed from the keyserver by its owner.
  • UNKNOWN KEY: key has not been registered on the BioMedIT portal. If it is your own key, please register it. If it is the key of someone else, please ask them to register their key.

Registering a new PGP key

Once the above prerequisites are met, perform the following steps to register your key and request its approval:

1. Connect to the BioMedIT portal and go to Profile and OpenPGP Keys tab.

2. Click on +OPENPGP KEY.

3. Add Key dialogue box will open. Enter your key’s fingerprint: please copy-paste it from your computer to avoid typing errors. Then click on the green search icon.

4. If your key is present on the Open PGP keyserver, the user ID and email associated with your key will be retrieved and displayed in the dialog box. Please double check that the value is correct.

5. If the displayed user ID and email values are correct, click on CONFIRM.

Your key is now registered and an approval request as been automatically sent to the DCC. Please note that the verification and approval of your key by the DCC is a manual process and may take a few days.

Note that your key’s approval status will be PENDING until approved by the DCC. Once approved, the status will change to APPROVED, at which point the key can be used to encrypt and decrypt data to be transferred into the BioMedIT network.

SSH Keys

From the SSH Keys tab, users can add their public SSH key for a specific project.

Registering a new SSH key

1. Click on +SSH KEY.
2. Select the project from the drop-down list
3. Copy the content of your public ssh key
4. click on SAVE

4 - Groups

From the Groups menu option, Data Providers can manage users and assign them roles.

Data Provider User roles and responsibilities

The Data Provider roles are intended to provide Data Providing institutions with the ability to manage the users involved in data transfers to BioMedIT and assign permission levels according to their responsibilities.

DP Manager

The DP Manager represents the Data Provider institution within the scope of BioMedIT. A DP Manager is responsible for the institution’s internal processes related to BioMedIT and delegates responsibilities to other users in their organization by assigning/removing DP roles. In addition, a DP Manager is responsible for maintaining and keeping the roles assigned up to date, i.e., if an employee left or changed responsibilities, and informing the BioMedIT Node and the DCC accordingly. Finally, the DP Manager delegates the internal operation coordination to the DP Coordinator.

DP Managers are:

• Responsible for the ensuring data provisioning at the Data Provider institution.
• Responsible for escalations and security incidents within the Data Provider.
• Responsible to assign/revoke the DP roles to other DP users.

DP Coordinator

The DP Coordinator is responsible for internally coordinating the DP’s readiness to send data, ensuring the legal compliance, i.e., DTUA, DTPA, etc. and all technical measures required from the DP side are in place for projects in which Data Provider institution participates. The DP Coordinator must send confirmation of readiness for data transfers to the DCC when required, and act as the single point of contact for follow-up questions and/or issues in the process.

DP Coordinators are:

• Responsible for coordinating internal data transfer processes of the Data Provider institution
• Responsible for confirmation of legal readiness for data transfers
• Responsible for confirmation of technical readiness for data transfers

DP Technical Admin

The DP Technical Admin is responsible for all technical tasks required for the setup and maintenance of a secure connection from the DP organization to the BioMedIT Node e.g., network components configuration. He is also responsible to support DP Data Engineer in the onboarding process. There could be more than one DP Technical Admin.

DP Technical Admins are:

• Responsible for the configuration of the network components from the DP side to permit data transfers.
• Responsible for supporting the onboarding of the DP Data Engineer(s).

DP Data Engineer

The DP Data Engineer is responsible to prepare, encrypt and sign the data packages, and transfer them from the DP organization to the assigned BioMedIT Node. There could be more than one DP Data Engineer.

DP Data Engineers are:

• Responsible for preparing and executing the data package transfers between the Data Provider and the assigned BioMedIT Node, following the BioMedIT process for secure data transfer.

DP Security Officer

The DP Security Officer is the designated point of contact from the DP organization to receive incident and security notifications from BioMedIT such as (but not limited to) scheduled and non-scheduled downtimes in response to security incidents, emergency changes and systems upgrades.

DP Security Officers are:

• Responsible for serving as a point of contact for incident, maintenance and security notifications from BioMedIT, and distributing them internally.

DP Viewer

A DP Viewer can monitor the status of data transfers from their DP institution.

How to add a user to a Data Provider group

To add a user to a group:

1. Click on the edit button of the group.
2. In the Users field, type the user’s email address and click on +USER.
3. When no more users need to be added to the group, click on SAVE.

5 - Projects

In the Projects menu option:

• Project users find a consolidated view of their projects, the data transfers, and the tools and resources enabled for the project.
• Project Leaders and Permission Managers can manage project users.
• Data Managers of a project can submit a data transfer request.

Projects view

From the project’s menu option, users can see the list of their projects.

The projects displayed can be filtered by using the Search function.

By clicking over a project, users can display the project’s details:

• Project Details tab
• Data Transfers tab
• Resources tab
• Services tab
• Users tab
• Additional information tab

Project Details tab

The details tab shows the project’s general settings:

• Code: A unique identifier for the project

• Hosting Node: Name and code of the node where the project is hosted

• Archived: Yes / No

• Expiration Date: Date when the project expires.

• Legal Approval Group: Group responsible to confirm compliance with legal basis and approve production DTRs.

• Data Specification Approval Group: Group responsible to review data transfer’s Data Specifications and approve production DTRs.

• Legal Support Contact: Contact email address to engage support about ethical and legal questions.

• Enable SSH Access: Indicates if SSH access has been enabled for the project.

• Enable Resources: Indicates if resources have been enabled for the project. The resources tab will be shown/hidden accordingly.

• Enable Services: Indicates if services have been enabled for the project. The services tab will be shown/hidden accordingly.

• Identity Provider: Source user identity provider specified for the project. By default is SWITCH edu-iD, but a node-specific pre-defined identity providers may be selected.

• IP Ranges: IP range(s) from where client connections to access B-spaces is permitted.
  If the user is connecting from an IP outside of the IP range, the message “Your IP address is not within the valid IP address ranges of the project” is displayed.

Data Transfers tab

The data transfers tab displays the list of data transfer requests submitted by the project.

• From the Search box, users can search for specific data transfer requests by any content as search criteria.

• +DATA TRANSFER: Function to submit a new Data Transfer Request. Note that this option is only visible to the project’s Data Manager(s). The data transfer request list is also accessible from the Data Transfers menu option.

Users tab

Displays the list of users and their role in the project.

Authorized flag:

This badge is displayed next to a project user when they have completed the mandatory BioMedIT training modules: Information Security Awareness Training

Additional information tab

Notes, comments and relevant information details. Note that this field is only editable by admins (Node Managers and BioMedIT Support).

Resources tab

Displays the access links to the node-specific tools and applications configured for the project. It offers these fields:

• Name
• Location - a valid URL that points to the resource
• Contact - a valid email address whom to contact
• Description - a simple textfield

These resources are defined per project only. Because of this limitation, we added the services tab (see below) which offer more flexibility.

Services tab

Similar to the resources tab but more flexible. Displays the node-specific tools assigned to a given project as well as the tools assigned to individual members of that project. The aim is that Portal serves as a central point for node-specific information. The data field (see example below) allows the use of markdown language which will be automatically nicely rendered as rich text in Portal.

To create a new entry, node admins simply need to issue a POST request:

POST /backend/projects/<project_pk>/services/

{
    "name": "Special Tools",
    "description": "A collection of special tools for a project",
    "data": "# Title\n*   feat 1 explained\n*   feat 2 explained",  # <- Markdown language
    "state": "CREATED" # valid states: INITIAL, PROGRESS, CREATED, LOCKED, ARCHIVED
}

Where the project_pk is the primary key of a given project (not the project code). Node admins and -viewers will then see the service(s) nicely rendered in the services tab.

To view, update or delete a project service entry, use the

/backend/projects/<project_pk>/services/<service_pk>/

endpoint and the GET, PUT or DELETE http verbs. service_pk is the automatically assigned primary key of a service.

In addition, services can also be assigned to project members, by sending a POST request to this endpoint:

POST /backend/projects/<project_pk>/members/<user_pk>/services

{
    "name": "Special Tools",
    "description": "A collection of special tools for a project",
    "data": "# Title\n*   feat 1 explained\n*   feat 2 explained",
    "state": "CREATED" # valid states: INITIAL, PROGRESS, CREATED, LOCKED, ARCHIVED
}

Where the project_pk is the primary key of a given project (not the project code) and user_pk the primary key of the user. If the user is not member of the specified project, you’ll receive a 404 error.

Once a project service is assigned to a project member, users then are able to see the current state of their assigned project services in the services tab.

To view, update or delete a project service entry, use the

/backend/projects/<project_pk>/members/<user_pk>/services/<service_pk>/

endpoint and the GET, PUT or DELETE http verbs. service_pk is the automatically assigned primary key of a service.

Note 1: these services serve information purposes only, have no implicit functionality. In particular, they do not trigger any mails being sent to the user.

Note 2: the service name must be unique and a service can only be assigned once to a project or project member. The service name can be freely chosen.

Note 3: currently the action field has no meaning or implicit functionality.

Note 4: there is no GUI planned to edit service information data.

User roles

User roles are set for each project. Each authorized BioMedIT user can have several user roles and can be assigned access to several projects.

Roles and responsibilities

Project Leaders (PL):

• responsible and accountable for the project
• responsible for the data lifecycle management of the project
• acts as contact point for escalations and security incidents within the project
• responsible to discuss the setup and configuration of the project space for the project with representatives of the BioMedIT Nodes
• responsible for case-by-case authorization of Data Transfers out of the B-space
• assigned to the project in the User Role of “Permissions Manager” by default and with that is responsible to assign authorized BioMedIT users
• responsible to assign the User Role of “Permissions Manager” to authorized BioMedIT users
• responsible to ensure that at least one authorized BioMedIT user was assigned to the project space in the User Role of “Data Manager”
• can act as “Permissions Manager” and/or “Data Manager” and/or “(default) User”
• responsible to revoke access rights to the project space
• informed about every user change (add/remove) via email notification
• there can be multiple PLs per project

Permissions Manager (PM):

• accountable to the PL
• each project must have at least one project member with the User Role of “Permissions Manager”
• responsible for assigning the User Roles of “(default) User” and “Data Manager” to authorized BioMedIT users and with that granting them access to the project space
• responsible to revoke access rights to the project space
• acts as contact for the new project members to support them with registration and authorization as users of BioMedIT

Data Manager (DM):

• accountable to the PL
• each project must have at least one project member with the User Role “Data Manager”
• responsible for unpacking and decryption of data packages within the B-space
• responsible to extract data from the B-space for transfer out of the project space only following explicit authorization of the PL
• responsible to place the request(s) for Data Transfer(s) from a Data Provider to the project

User:

• accountable to the PL
• has access to one or several project spaces following authorization
• responsible for data processing within the B-space

No Role:

• accountable to the PL
• can access the project’s details in the Portal, but has no access to the B-space.
• mutually exclusive with other roles

Managing project users

When clicking on the Edit project button the top-right corner, you will be taken to edit page.

Adding users to a project

1. In the Users field, enter the user’s email address and click on +USER. Note that the user(s) must have an account in the portal.
2. You will be asked to confirm the user’s details before adding it to the project.
3. Review the details of the user, and click on ADD to confirm it.
4. You will return to the list of project users. Assign a role to the user by clicking on the corresponding checkbox(es).
5. Click on SAVE.

Removing users from a project

To remove users from the project, the Project Leader or the Permissions Manager should:

• Click on the 'x' next to the user’s name.
• After any change, click on SAVE

Submitting a Data Transfer Request

To submit a Data Transfer Request (DTR), click on +Data transfer. The data transfer creation form will be displayed.

Complete the required fields:

• Unlimited / One Package: Select if the DTR will cover one or multiple data transfers

• Data Provider: Select the Data Provider from the drop-down list

• TEST / PRODUCTION: Select TEST if mock data will be sent, or PRODUCTION if the data will contain patient real data

• Additional Data Recipients: Enter the email(s) of the data recipient(s) and click on the +USER button.
  Note that recipients can only be users with the Data Manager role in the project.

• Legal Basis: If transferring real data (purpose PRODUCTION), enter the legal agreement (i.e. DTUA, DTPA) document name

• Data Specification: If transferring real data (purpose PRODUCTION), include the link to the Data Specification
  

  Example: https://git.dcc.sib.swiss/admin/projects/project-space/example-project/data-transfer/-/tree/main/data-transfer-1?ref_type=heads

Click on SAVE.

A new DTR will be created in INITIAL status. Confirmation emails with the DTR’s details are sent to the DTR requester, recipient(s), and approvers.

DTR Approvals

When the DTR is created, the following approval requests are submitted in parallel:

1. Node(s) Approval: As data processors, the involved node(s) must confirm the presence of a pre-existing legal basis for the data transfer and ensure that the necessary technical infrastructure is in place to support it.

2. Legal Compliance Approval: For SPHN/NDS projects, facilitated by the DCC ELSI Help Desk group who verifies the existence of a legal basis (e.g., DTUA, Consortium agreement) for the data transfer. For non-SPHN projects, a dedicated local Legal Compliance group may be optionally configured.

3. Data Specification Approval: For SPHN projects, the DCC will review and approve the data specification documents referenced in the ‘Data Specification’ link. This process ensures the compliance with the SPHN Semantic Interoperability Framework.

4. Data Provider Coordinator Approval: This approval request is triggered only when the previous approvers, (1),(2) and (3) have submitted theirs.

The Data Provider Coordinator is then requested to confirm if the data delivery has been approved through their internal governance processes.

When all approvers approve the request, the DTR status changes to AUTHORIZED, and data can then be transferred. Notification emails are sent to all parties involved in the data transfer:

If any of them rejects the DTR, its status is set to UNAUTHORIZED.

Monitoring the approval status of a Data Transfer Request

The status of a DTR is displayed in the last column of the DTR list.

Approval Status

• INITIAL: The DTR was submitted, but it has not yet been approved.
• AUTHORIZED: All approvers have authorized the DTR. The Data Provider can now send the data.
• EXPIRED: The Data Provider sent the maximum allowed number of data packages, and no additional data can be sent under this DTR ID
• UNAUTHORIZED: The DTR was previously authorized but is currently unauthorized for some reason (i.e., The BioMedIT Node is offline, problems with user permissions, issues on the Data Provider's end, etc.)|

Data Transfer details

When clicking on a particular data transfer, a pop-up window shows additional information

• Details tab
• Logs tab
• Approvals tab

Details tab

Displays the attribute values of the DTR as submitted by the project’s data manager.

Logs tab

Displays the individual data packages transfer logs - routing information and whether the data has arrived to the project workspace.

Approvals tab

Displays the current approval status of a DTR by all approval groups.

6 - Data Transfers

In the Data Transfers menu option:

• Data Managers and Data Providers can search and view the list of submitted Data Transfers Requests (DTRs), monitor their authorization status and transfer logs
• Data Providers (DP Data Engineers) can fetch their credentials to transfer data to a research project.
• Data Provider Coordinators can approve or reject a DTR

DTR Approval status

The approval status of a DTR is displayed in the last column of the table:

• INITIAL: The DTR was submitted, but it has not yet been approved by the Data Provider and/or the BioMedIT node(s).
• AUTHORIZED: All approval groups have authorized the DTR.  The Data Provider can now send the data.
• EXPIRED: The Data Provider sent the maximum allowed number of data packages, and no additional data can be sent under this DTR ID
• UNAUTHORIZED: The DTR was previously authorized but is currently unauthorized for some reason (i.e., The BioMedIT Node is offline, problems with user permissions, issues on the Data Provider's end, etc.)

Additional details about which group approved when are shown when clicking on a specific DTR. See approval details

Data Transfer details

When clicking on a particular DTR, a pop-up window shows additional information

• Details tab
• Approvals tab
• Credentials tab
• Logs tab

DTR’s details are accessible using the following link structure: https://portal.dcc.sib.swiss/data-transfers/dtr_id

Details tab

Displays the attribute values of the DTR, as submitted by the project’s data manager:

• Project: Name of the project
• Transfer ID: Unique DTR identifier
• Data Provider: the Data Provider code
• Status: Approval status of the DTR
• Max Number of packages: 1 (single transfer) or UNLIMITED (multiple data transfers)
• Transferred Packages: Count of packages sent so far under this DTR ID
• Requestor: Name of the Data Manager that submitted the DTR
• Data Specification: link to the Data Specification
• Purpose: TEST (for mock data) / PRODUCTION (for patient real data)
• Legal Basis: Legal agreement (i.e. DTUA, DTPA) document name

Approvals tab

Displays the current approval status of a DTR.

Credentials tab

From this option, DP Data Engineers can fetch their credentials, required for authentication and authorization to transfer data when the transfer method is S3/HTTPs.

To fetch and copy their credentials, as DP Data Engineer:

• click on FETCH CREDENTIALS
• click on COPY ALL

Logs tab

Displays the individual data packages transfer logs - routing information and whether the data has arrived to the project workspace.

Approving DTRs

When the DTR is submitted by a project’s Data Manager, the groups involved in the data transfer will receive a notification by email with all the details, for their information or for their action (request for approval), depending on the case, as explained below.

Approvals

When a DTR is submitted by a Data Manager to a research project, the following approvals must be collected:

1. Node(s) Approval: As data processors, the involved node(s) must confirm the presence of a pre-existing legal basis for the data transfer and ensure that the necessary technical infrastructure is in place to support it.

2. Legal Compliance Approval: For SPHN/NDS projects, facilitated by the DCC ELSI Help Desk group who verifies the existence of a legal basis (e.g., DTUA, Consortium agreement) for the data transfer. For non-SPHN projects, a dedicated local Legal Compliance group may be optionally configured.

3. DCC Data Specification Approval: For SPHN projects, the DCC will review and approve the data specification documents referenced in the ‘Data Specification’ link. This process ensures the compliance with the SPHN Semantic Interoperability Framework.

Only when the above groups, (1), (2) and (3) confirm their approval, the DP Coordinator is requested to submit theirs:

By clicking on the link in the email above (https://portal.dcc.sib.swiss/data-transfers/<DTR_ID>), DP Coordinators will be redirected to the BioMedIT Portal to approve or rejects the request.

To approve the DTR, click on APPROVE and declare, by clicking on the checkboxes, if:

• All technical measures are in place to send the data
• There is an existing legal basis for the Data Transfer
• This data delivery has been approved through internal governance processes

Then, click on APPROVE.

To reject the DTR, click on REJECT and provide a reason for the rejecting. Then, click on REJECT.

When all approvers approve the request, the DTR status changes to AUTHORIZED, and data can then be transferred. Notification emails are sent to all parties involved in the data transfer:

If any of them rejects the DTR, its status is set to UNAUTHORIZED.

Download data transfer list

By clicking on the download icon at the top-right corner, users can download the list of DTRs in csv format.

7 - Contact Us

It is the contact form to submit feature requests or support to the BioMedIT Help Desk (biomedit@sib.swiss).

8 - Central Services

8.1 - DCC GIT

1. Login to GitLab

1.1 GitLab is available via federated login from BioMedIT portal’s Quick Access link:

1.2 The following page will be displayed.

Click on Federated Login

2. Resources

• Get started with GitLab
• GitLab Learn → Watch videos and self-driven demos
• GitLab docs → Access step-by-step tutorials and guides

8.2 - Harbor

1. How to request access

1.1 Registry is available via federated login from the BioMedIT portal’s Quick Access links:

1.2 Click on the button: Login via OIDC provider

2. Resources

• Working with projects
• Project configuration
• Working with images
• Using the API explorer