This section of the User Guide describes the features available to Project Administrators to manage their Project.

Each Project is owned by a Project Administrator, a role analogous to an academic Principal Investigator. More than one person can hold the Project Administrator role, allowing for role delegation and backup. Creation of your own Project can be requested by submitting an inquiry (see Contact Us).

Getting Access to your Project

As a Project Administrator, you can start working in your Project after the Platform Administrator has created it and invited you. You’ll receive an email containing an invitation link - if it’s your first time using the platform, the link will direct you to register your user account; if you already have a user account, the link will take you to the login page where you can enter your username and password to open your Project from the Project Landing Page. For more information, see Getting Started with HealthDataCloud.

File Access for Project Administrators

As a Project Administrator, when you launch your Project the Project Canvas view displays file activity statistics from all Project members, not just your own. In the File Explorer, you have access to all Project member folders in the Green Room and Core, and can perform actions (upload, download, tag, annotate, delete) on any file.

Modifying Project General Information

When the Platform Administrator creates your Project, the Name and Code are assigned and other general information may have been initialized. The Project Code cannot be changed, but as a Project Administrator you can edit the other Project’s General Information in the Project Settings page (not available to regular Project members).

To edit your Project’s General Information (Project Administrator role),

1. Launch the Project and click the Settings icon in the left menu bar.
2. Click the General Information tab. If changes are desired, click the icon in the upper right corner to open Edit mode.
3. Make the necessary changes.
4. Click Save to save the changes or Cancel to exit without saving.

General Information includes the following:

• Project Code (required, cannot be changed):

  • Uniquely identifies the Project across the platform.
  • Between 1-32 characters. Must start with a letter and contain only lower case letters (a-z) and numbers (0-9)

• Project Name (required):

  • A short name for your project to differentiate it from other projects.
  • Maximum 100 characters

• Description:

  • A longer description of the Project to add more context and inform users of study details.
  • Maximum 250 characters.

• Project Administrator:

  • Displays the names of the Project Administrators assigned to the Project as email links.
  • Auto-populated. To add or remove Project Administrators, go to the Members page (see Managing Project Members)

• Tags:

  • Keywords to help make your Project findable.
  • Between 1 and 32 characters and may only contain lowercase letters, numbers and/or hyphens.

• Icon:

  • An image uploaded from your computer to make your project more findable.
  • Recommended size 200 x 200 pixels.

• Visibility:

  • A setting that controls the Project’s visibility in the Project Landing Page (ON/OFF).
  • By default, visibility is set to ON, meaning that the Project’s general information is listed in the Project Landing Page All Projects tab and is visible to all Platform users. Turning this setting OFF hides the Project in the Project Landing Page from everyone except Project members.

Managing Project Data

Each Project has its own Core and Green Room areas. The Green Room is the landing zone for all files uploaded to the platform. In the Projects' Green Room, files are only visible to the respective User who uploaded them, as well as the corresponding Project Administrators. In contrast to the isolated Green Room, the Core of each Project serves as the common data storage area of the Project, where all Project members (except Project Contributors, see Project Roles below) can access each others’ files, create file collections, and use the workspace tools to open files and perform analyses.

In order to ensure compliance of all data in the Core with the Projects´ respective data management plan, the transfer of data from the isolated Green Room to the collaboratively used Core is a tightly controlled process, which can only be performed by a Project Administrator. Therefore, Project members who are not Project Administrators have to select files and/or folders in their own folder in the Projects´ Green Room and submit a Copy-to-Core request to the Project Administrator, in order to copy the selected files to the Projects´ Core (for more information on this process, see Working with HDC Project Files in the Portal > Requesting File Copy from the Green Room to the Core). Essentially, this grants Project Administrators full control of the data in their Projects` Core, for instance to ensure that all data are pseudonymized to the extent necessary to comply with the Projects` data management plan.

See the following sections for details on how Project Administrators can copy files from the Green Room to the Core, and process Copy-to-Core requests.

Copying files from the Green Room to Core

Copying files from the Green Room to the Core can only be performed by users with the Project Administrator role in the corresponding Project, or by Platform Administrators.

1. In the Project File Explorer, open the Green Room and navigate to the folder where the file(s) are stored.
2. Select one or more files and/or folders to be copied by clicking the checkbox beside each one, then select Copy to Core.
3. In the confirmation pop-up, select a destination folder. 
4. A confirmation code is randomly generated. Type the code in the entry box to confirm your intention to copy the selected files to the specified destination, then click Confirm. 
5. Another popup confirms the action was completed. Click Close to dismiss.

After completing the Copy action, your files are visible in the File Explorer in the specified destination folder in the Core and can be accessed by all Project members (except Project contributors, see Project Roles below).

Processing Copy to Core Requests

Project members cannot copy files to the Core themselves but can select files and/or folders in their Green Room folder and submit a Copy to Core request to the Project Administrator to copy the selected files to the Core. Project Administrators can approve or deny each file in the request individually, then complete the request and notify the user.

Approve or Deny selected files

Project Administrators are notified about pending Copy to Core requests with a red notification dot on the Requests icon. The following steps describe how to review, approve, and/or deny Copy to Core requests:

After completing the above steps, approved files/folders will be copied to the destination in the Core that was specified in the copy to core request. All Project members (except Project Contributors, see Project Roles below) can now access the files via the File Explorer or workbench tools. Denied files are not copied.

Close the Request

After Approving or Denying every file/folder in the request, it’s time to close the request and notify the user. To close the request,

1. Click Close Request & Notify User.
   • If you haven't approved or denied all the files/folders in the request, a popup window appears reminding you to go back and approve or deny the remaining files.  
   • If you have approved or denied all the files/folders in the request, a popup window prompts you to confirm closure of this request and enter optional Review notes that will be shared with the requester.
2. Click Confirm. 
3. An email notification is sent to the requester, and the request appears in the Completed tab in the Requests panel.

After completing the above steps, the request status moves to Completed.

Considerations

• Large files may take some time to copy to the Core. To view the progress, open the File Status panel in the Main Menu.
• If a file with same name already exists in the destination folder in the Core, the file will be copied and a time-stamp will be appended to its filename.
• If a folder with the same name already exists in the destination, the files will be copied into the existing folder and a 10-digit time-based integer hash will be appended to the duplicate filenames.

• The original file remains in the Green Room and a copy of the file is moved to the destination folder in the Core. The new Core file metadata and Data Lineage properties are updated:

  • Created - the timestamp indicating the time the copy was created.
  • Data Lineage Pipeline - copy - the time the file copy landed in the Core.

Managing Project Members

Project Administrators have the flexibility to add or remove Project members, and change users' roles within the Project.

To manage Project membership for your Project as Project Administrator role,

1. Launch the Project and click the Project Members icon in the left menu bar.
2. The Members table displays all the members of the project. Use the search, sort, and page navigation tools to find users.
3. Choose one of the available options described below to manage your Project members.

Adding Project Members

Project Administrators can add new members to the Project:

1. Launch your Project and open the Project Members page, then click + Add Member.
2. Enter the user’s email address and assign a Project Role (see Project Roles, below).
3. Click Submit to continue, or Cancel to exit without adding the member.
4. A second pop-up window prompts you to review the provided information. Click Send to complete the invitation, or Cancel to exit.

If the invited member already has a user account on the platform, they are added to the Project immediately and they will receive an email notification that their new Project access has been granted. Their member details will appear in the members page.

If the invited member doesn’t have a user account on the platform, they will receive an email with instructions on completing their account registration. For details on this process, see Getting Started. For new platform account holders, please note the following:

• Between the time of invitation and account activation, the user’s invitation status is listed as Pending in the Invitations tab.
• After the invited member completes their account activation, their member details appear in the Members page and their invitation status is listed as Completed in the Invitations tab.

Project Roles

The following table describes available Project roles and their permissioned data and project operations:

Note: Be reminded that Platform Administrators hold no Project specific role, and are, therefore, not listed in the table above. However, within each Project, they have - by default - the same permissions as a Project Administrator.

Viewing Project Member Profiles and Account Activities

Project Administrators can review the Project membership, member profiles and account activities.

1. Launch your Project and open the Project Members page.
2. Click the Action icon (three vertical dots) in the member’s entry in the Members table and click Profile.
3. The Member Profile page displays basic profile information and history of actions in their account (invited when and by whom, date activated, role changes).

Changing Project Member Roles

Project Administrators can change the role of any Project member other than themselves.

1. Launch your Project and open the Members table in the Project Members page.
2. In the member’s entry, click Change Role and select a new role from the dropdown menu.
3. A popup window prompts you to confirm the change. Click OK to confirm, or Cancel to exit without making the change.

After clicking OK, the role change takes effect immediately and the Project member will receive an email notification confirming their new role assignment.

Considerations

• Assigning a Project Member to a less privileged role may cause them to lose access to Project data they previously had access to.
• As a Project Administrator you cannot change your own role, but another Project Administrator can change your role.

Removing Members from the Project

Project Administrators can remove members from the Project.

1. Launch your Project and open the Members table on the Project members page.
2. Click the Action icon (three vertical dots) in the member’s entry and click Delete.
3. A popup window prompts you to confirm the change. Click OK to confirm, or Cancel to exit without making the change.

After clicking OK, the member is removed from the Project immediately. Their membership in other Projects is not affected. The member will not receive an email notification.

Note: removing a member from a Project removes their access to all the Project data in the Green Room, Core, and Workspace VMs. However, the user will continue to have access to Project data held in any Datasets they have created as long as their user account is active.

Managing Project Workspace Tools

Workspace tools like Jupyterhub enable your Project members to work with the Project data right within the HDC platform, fostering remote collaboration. In addition, the workspace tool XWiki allows your Project members to collaboratively work on your Project wiki documentation. Integrated Workspace tools are configured at the time of Project creation, or later, by a Platform Administrator.

As Project Administrator, you can check the deployment status of Workspace tools by opening the Project Settings page and clicking the Workspace tab.

If you need a Workspace tool deployed for the project, please contact a Platform Administrator.

Jupyterhub

After Jupyterhub is deployed for the Project, members can click Jupyterhub in the Workspace icon group to launch their own Jupyter environment. Login is seamless with single sign-on - just click Sign in with Keycloak. See Using Jupyterhub for more details on how to use the application in the platform.

Guacamole

Apache Guacamole is a clientless remote desktop gateway that provides access to Project Virtual Machines (VMs). Guacamole is not automatically deployed when the Project is created. Project Administrators can submit a support request to have Guacamole and connected VMs deployed for their Project.

After the Guacamole application and the VMs have been set up by a Platform Administrator, members can submit access requests for Guacamole-connected VMs (see Using Apache Guacamole) and Project Administrators can grant access to the requested VM(s) following the instructions below, Granting Access to Guacamole VMs.

Granting Access to Guacamole VMs

Project Administrators can grant access to Guacamole-connected Virtual Machines (VMs) requested by Project Members (including themselves).

1. Launch your Project and click the Requests icon from the Project left menu bar.
2. Click the Guacamole VM Request tab. The table displays Project members who have requested access. The Status column differentiates users whose VM access has been previously completed from those who are waiting for access.
3. Please reach out to the Platform Admin by creating a support ticket and provide the following details:
   • The project code
   • The user who shall be granted access to a VM, including the associated email address
   • The VM for which access shall be granted
4. Please wait for confirmation that the VM-specific account has been created before proceeding with step 5.
5. In the VM column, select one or more connected VMs and click Confirm Selection.
6. Click Complete to finish the setup.
7. The requester will receive an email notification that their access was granted and they can launch Guacamole to access the selected VMs.

See Using Guacamole in HDC for more details on how to use the application in the platform.

Superset

After Superset is deployed for the Project, members can click Superset in the Workspace icon group to launch their own Superset instance. Login is seamless with single sign-on, and users will have access to the visualization tools to design charts and visualizations, and the SQL lab to query the data in the project-specific database. See Using Superset for more details on how to use the application in the platform.

XWiki

After XWiki is deployed for the Project, members can click XWiki in the Workspace icon group to launch the application and be logged in seamlessly with single sign-on. See Using XWiki for more details on how to use the application in the platform.

Creating Project Announcements

Project Administrators can use the Announcements page to send messages to all Project members to convey relevant Project news and information. Project Members can use this page to view Project announcements.

To create a Project announcement as Project Administrator,

1. Launch your Project and click the Announcements icon in the left menu bar.
2. In the Create new announcement window, enter your announcement (maximum length 250 characters) and click Publish.
3. Your announcement will be visible to all Project members in Announcements page of the corresponding Project, as well as in their Notifications area (accessible via the orange bell icon in the navigation bar at the top of the portal website), and in their Newsfeed on the Dashboard page.

Managing File Attribute Templates

Project Administrators can create and configure File Attribute templates that will be available to all Project Members to annotate files during or after upload (see Working with HDC Project Files in the Portal > Adding and Modifying File Attributes).

Creating a File Attribute Template

To create a new File Attribute template for your project as Project Administrator,

1. Launch your Project and click on the Project Settings icon.
2. Select the File Attributes tab and click Create New Attribute Template.
3. Enter a name for the Template and click Next Step.

4. Click + Add Attribute to create a new attribute and configure the key parameters:

   • Name: Provide the name of the attribute (letters or numbers, no spaces, maximum 32 characters).
   • Type: Select the type of information to be collected (text, multiple choice). Text fields will allow entries of up to 100 characters.
   • Value: If you selected multiple choice as type, you can define the available value options (maximum 32 characters each), pressing Enter after each entry.
   • Optional: Specify whether the Attribute is optional or mandatory (optional by default). Uncheck the box if the Attribute is mandatory.
5. Click the checkmark to save the new field or X to clear the field.
6. To add more fields, repeat steps 4-5 until all fields have been added.
7. Review the newly created fields for accuracy and completeness. Be sure to click the checkmark in the Actions column beside each field to save the entry, or X to discard the field. Once a field is saved, use the Edit or Delete icons to make any changes. Note: after a File Attribute template has been saved, new fields can be added to the template but existing fields cannot be edited or removed, and any new attributes added to the template must be Optional.
8. Click Create. 

Your new File Attribute template is saved and Project Members will be able to see the template and annotate files with these Attributes. For more details on how to annotate files, see Working with HDC Project Files in the Portal > Adding and Modifying File Attributes.

You can create multiple File Attribute templates for the Project, but a Project file can only be annotated with a single File Attribute template.

Managing a File Attributes Template

After a File Attribute template has been created, a Project Administrator can make limited changes to the template, delete it, or export it as a JSON file.

1. Launch your Project and click on the Project Settings icon.
2. Select the File Attributes tab and locate an existing template.
3. Click an available action:
   • Rename: When an Attribute template is renamed, all Files annotated with the template will show the new template name. Click Save, or Cancel to exit without making the change.
   • Delete: An Attribute template can only be deleted if it has not yet been used to annotate any files.
   • Export: Click to download the Attributes template as a JSON file.
   • Add Attribute: Attributes denoted as Optional can be added to the template, as described above in step 4 of the section Creating a File Attribute Template. Click the checkmark to save each addition.
     • Attributes denoted as Mandatory cannot be added.
     • Existing attributes cannot be edited or removed.
4. The changes will be effective for any new File Attribute annotations.

Importing File Attribute Templates

Instead of using the Project Settings page to create Attributes template, Project Administrators can import the template configuration as a JSON file.

1. On your local computer, create and save a JSON file containing your annotations, see Formatting Guideline for JSON File Attribute Templates below.
2. Launch your Project and click on the Settings icon.
3. Select the File Attributes and click Import Attribute Template.  
4. Enter an Attribute Template name, upload the JSON file you created, then click OK. If there are errors in the JSON file, a parse error message will be returned. Please review the Formatting Guideline for JSON File Attribute Templates section below, then check your uploaded file and try again after adapting it accordingly.
5. Once the file has been successfully uploaded and saved, it will be available to all Project Members to annotate files.

Formatting Guideline for JSON File Attribute Templates

JSON is built around two structures:

• Objects

  • Key-value pairs
  • Surrounded by curly brackets ({})

• Arrays

  • Lists of items
  • Surrounded by square brackets ([])

Parameters for File Attributes JSON templates are as follows:

• Name: The Attribute name (letters or numbers, no spaces).
• Type: The type of information to be collected (text, multiple choice)
• Value: If the Type is Multiple Choice, a list of the accepted values, separated by commas.
• Optional: Default is true. Set to false if the Attribute should be mandatory on collection.

The following example depicts a File Attribute template created in the Project Settings menu and the corresponding JSON file format. You can use this example as a guideline to create your own JSON file.

Template created in the Project Settings menu:

Corresponding JSON file format:

Deleting and Archiving Projects

Please contact a Platform Administrator if you need to delete or archive your Project.

Copyright © 2023-2024 Indoc Systems.

HealthDataCloud is powered by Pilot technology, a product of Indoc Systems.