Search

Migrating Workspaces from Legacy Workbench to Researcher Workbench 2.0

  • Updated

Table of Contents

Overview

Researcher Workbench 2.0 offers an updated user experience with optimized tools, improved performance, and more to support your research. To take full advantage of the powerful platform capabilities, you can migrate your workspaces from the legacy Workbench to Researcher Workbench 2.0 using a user-interface prompted tool.

This guide provides essential information on accessing the Researcher Workbench 2.0, preparing your existing workspaces for migration, completing workspace migration, and updating your migrated workspace for use in Researcher Workbench 2.0. Please review all sections carefully to ensure a successful migration. All workspaces must be fully migrated by June 30, 2026 after which Researcher Workbench 2.0 will serve as the central workbench platform.

For a PDF copy of this guide, see here. 

Figure 1 - image of workspace migration process
Figure 1 - Workspace Migration Process Overview

Before You Begin Migration

Step 1: Confirm Eligibility and Access Requirements

Before you can begin migrating a workspace to Researcher Workbench 2.0, you must confirm that both you and your workspace meet the migration eligibility requirements outlined below. Migration cannot proceed until all required items are completed.

  • Your annual All of Us data access requirements are complete and up to date. If these requirements are expired, you will be unable to access workspaces in the Researcher Workbench. Once a year, you are required to complete three steps to maintain your access to the Researcher Workbench and the All of Us dataset:
    • Complete refresher modules of the Responsible Conduct of Research Training.
    • Re-attest to the Data User Code of Conduct.
    • Update and/or confirm personal contact information and institutional affiliation.
  • You have signed in to Researcher Workbench 2.0
    • You must log in to Research Workbench 2.0 at least once before migration. To learn more, please see detailed information in the Researcher Workbench 2.0 getting started guide here.
    • During your first login, you will be prompted to review and accept the Verily Terms of Service (TOS).
    • Accepting the TOS confirms your eligibility to create and manage workspaces in Researcher Workbench 2.0.
  • Your workspace(s) is associated with an active billing account
    • Both your legacy workspace and your Researcher Workbench 2.0 workspace must be linked to a valid billing account for migration to succeed.
    • You can use one of the following billing options:
      • Your initial All of Us credits (if available and not expired or exhausted), or
      • A personal or institutional Google Cloud Platform (GCP) billing account
    • Before migrating, confirm that the legacy workspace is linked to either the All of Us initial credits or a valid GCP billing account.
    • Researcher Workbench 2.0 must also have an active billing pod available. As with the legacy workbench, the pod determines the billing source for storage and compute resources. Migration cannot proceed without an active billing pod.
  • Coordinate with your collaborators
    • Workspace migration can only be initiated by workspace Owners or the workspace Creator. Users with other roles (such as Writers or Readers) do not have permission to initiate migration. If your workspace has multiple collaborators, we strongly recommend coordinating with the workspace Owner(s) before proceeding with migration. Once a workspace has been successfully migrated, all collaborators will see a “Migrated” signage in the workspace.

ℹ️ Important Notes:

While preparing for migration, please take note of the following:

  • You can still duplicate existing workspaces in legacy Workbench, which are required to update older CDR versions (v3-6) to a supported version (CDR v7-8).
  • Your legacy workspace will not be locked after migration. However, changes made in Researcher Workbench 1.0 after migration will not automatically sync to Researcher Workbench 2.0.
Step 1: Confirm Eligibility — Completion Checklist

Before moving on to the next step, please confirm that you have

  • Confirmed all All of Us annual data access requirements are up to date
  • Logged into Researcher Workbench 2.0 and accepted the Verily Terms of Service
  • Ensured your legacy workspace is linked to a valid billing account and a billing pod is available in Researcher Workbench 2.0

Once all items are complete, you are ready to continue preparing your workspace for migration.

Step 2: Prepare and Clean Up Your Workspaces

Before beginning migration, we recommend reviewing and preparing your existing workspaces to ensure only essential workspaces and files are migrated. There are several workspace requirements to meet eligibility for migration.

  • Your workspace uses a supported CDR version.
    • Only workspaces using CDR version 7 or 8 are eligible for migration.
    • Workspaces using CDR versions 3-6 will not be migrated by default.
      • If you wish to continue working in a workspace that has an older CDR, you must duplicate the workspace and select CDR v7 or v8.
      • The duplicated workspace can then be migrated.
  • All required files are stored in the workspace bucket.

ℹ️Tip - Review this clip to learn more about accessing the persistent disk and workspace bucket via command line code. 

Review and categorize all workspaces

Review your list of workspaces in legacy Workbench and decide which workspaces you want to migrate, archive, or permanently delete (if no longer needed).

If your project work is split across multiple workspaces, consider consolidating related work into a smaller number of workspaces prior to migration.

Note: Workspaces that are not manually migrated will be archived through a system‑led archival process. Archived workspaces are not active for analysis but may be recovered during the retention period. More information on this archival process will be provided soon.

Preserve cohort and dataset logic before migration

If you used the Cohort Builder or Dataset Builder in legacy Workbench:

  • Record your inclusion and exclusion criteria, concept definitions, and logic.
  • Cohorts, datasets, and concept sets created using the legacy Workbench point-and-click tools will not be migrated.
  • However, any query or script using the Cohort Builder and Dataset Builder that is saved within a notebook or another file in your workspace bucket will be available in the file that is migrated.

You will be able to recreate these results in Researcher Workbench 2.0 using the Data Explorer tool.

Delete unneeded workspaces and stored files

Deleting unused workspaces and files streamlines migration and reduces ongoing storage costs.

How to delete a workspace

Click "dots.png"
workspace_delete.png

Select “Delete”
select_delete.png
 

Type “DELETE”
type_delete.png
 

Click “Delete Workspace” to confirm you want to permanently delete your workspace:
warning_delete.png

 

Note: Deleted workspaces and files cannot be recovered.

We recommend you also delete any cohorts, concept sets, datasets, and notebooks in your workspace that were created for testing purposes.

cohorts_delete.png

For additional guidance, see Managing Workspaces.
 

Review and Address Persistent Disks (PDs)

Persistent disks are not supported in Researcher Workbench 2.0. Files stored on persistent disks are not included in workspace migration and must be moved to the workspace bucket to be retained.

To review workspaces using a persistent disk, select "Cloud Environments" under "Data Access Requirements" in the menu. For more information about persistent disk, see these resources:

Deleting Persistent Disks – Option 1

  • Click on the Persistent disk menu icon

    All of Us hamburger menu

  • Select Cloud Environments in the menu.

    Cloud Environments menu option

  • Click the Delete button under Action.

    Persistent disk delete action

    Note: If you have a running environment, you will not be able to delete a persistent disk. You will need to delete the cloud analysis environment, then delete the disk. 

Deleting Persistent Disks – Option 2

  • In the workspace, click on the Jupyter icon.

    Jupyter icon used to access the persistent disk options

  • In the pop-up, if you see the option DELETE PERSISTENT DISK at the bottom in blue, then you DO have an active persistent disk being used. If you do not see this option, or it is grayed out, then you DO NOT have an active persistent disk.

    Persistent disk delete option in the Jupyter environment

  • Migrate files from the persistent disk to the workspace bucket when applicable.

Manage workspaces using CDR v3-v6

As previously noted, workspaces using CDR v3-v6 are not eligible for migration. You have the following options:

  • Delete the workspace (if it is no longer needed), or
  • Duplicate the workspace and upgrade it to CDR v7 or v8 in preparation for migration

If you do not plan to upgrade or migrate the workspace but want to keep a record of your work, such as code, scripts, or summary statistics, you may download allowable files for local storage (for example, notebook files like .ipynb or .json). Please note that participant-level data may not be downloaded, in accordance with the Data User Code of Conduct. All Jupyter notebook outputs, .R or .Rmd, or SAS outputs must be cleared prior to downloading. 

Before downloading any files from the Researcher Workbench, please review the following policies and resources: 

Step 2: Workspace Clean‑Up — Completion Checklist

Before moving on to migration, confirm that you have

  • Categorized your workspaces (migrate, archive, delete)
  • Recorded cohort and dataset logic
  • Deleted unused workspaces and files
  • Moved all persistent disk files to the workspace bucket
  • Updated or duplicated older CDR (v3–v6) workspaces, if needed

Once these steps are complete, your workspaces are ready for migration.

Start a Workspace Migration

Step 3: Migrate Your Workspace

Once you have confirmed eligibility and prepared your workspace, you can begin migrating your workspace to Researcher Workbench 2.0. 

Note: Workspace migration can only be initiated by a workspace Owner or the workspace Creator. If your workspace has multiple collaborators, please coordinate accordingly before proceeding.

Workspace migration is initiated from legacy Workbench and applies to existing legacy Workbench workspaces. Once logged into legacy Workbench, guided prompts are available to ensure a successful migration.

How to Migrate a Workspace

  1. Log into legacy Workbench at https://workbench.researchallofus.org/login.
     

  2. On the landing page, there is information on the migration process with quick links. Select “Go to workspaces” to open a list of your workspaces.
    migration_banner.png

     

  3. Select the Researcher Workbench 1.0 workspace you want to migrate. You will be prompted to begin the migration process. 
    ws_new_1.png
     

  4. Under the “Data” tab of your workspace, review the eligibility checks and informational guidance. Then select "Get Started."
    ws_new_2.png

    ws_new_3.png
     

  5. On the next page, select the billing pod you want the Researcher Workbench 2.0 to use.  

Note: Researcher Workbench 2.0 billing pods you have added within the last few hours may not immediately display in the drop-down menu. If you’ve recently been added to a billing pod and don’t see it listed as an option, please check back in 24 hours.

ws_new_4.png
  1. Select “Start migration” to initiate the migration.

The migration process is now automated and will

  • Create a new Researcher Workbench 2.0 workspace
  • Transfer all files stored in the workspace bucket
  • Copy required workspace metadata and access policies

During Migration

While migration is in progress:

  • No additional action is required from you
  • You may continue to access legacy Workbench, but your workspace may be temporarily unavailable while migration is in progress. The time required to complete migration may vary depending on the size of your workspace.
Once Migration Completes

Once migration finishes, confirm the following:

  • Your workspace is available in Researcher Workbench 2.0.
  • You can view your migrated workspace by opening the Researcher Workbench 2.0 landing page and selecting the Workspaces tab.
  • Your migrated workspace appears in the list with the same title it had in Researcher Workbench 1.0 at the time of migration.

To learn more about working with workspaces in Researcher Workbench 2.0, see Researcher Workbench Getting Started resources

You are now ready to review and validate your migrated workspace.

After You Have Migrated

Step 4: Validate and Continue Work in Researcher Workbench 2.0

After your workspace migration to Researcher Workbench 2.0 is complete, you should review your migrated workspace and take a few follow-up steps before continuing your analysis.

Confirm Your Migrated Workspace

Once migration finishes,

  • Open the migrated workspace in Researcher Workbench 2.0.
  • Navigate to the Resources tab to confirm that your workspace files are present. Your bucket contents will be relocated to a folder named rw-migration-XXXX, where XXXX is an alphanumeric string. To view a preview of the bucket contents, select "Browse".
WS_4.png
WS_5.png
  • Alternatively, you can view your notebooks through the Jupyter File Management System. 
  • Workspace buckets within Researcher Workbench 2.0 are configured with an auto-mount feature. Your migrated files will be placed within the auto-mounted bucket which is called workspace.  

ws_new_5.png

  • By double-clicking the workspace folder, you will be taken to the next folder level which will then contain your migrated bucket contents from legacy Workbench. Your migrated data will be in a folder starting with rw-migration-aou-rw-XXXXXXXX

ws_new_6.png

  • Verify that notebooks, scripts, and data files open as expected.

Workspace files stored in the workspace bucket should now be accessible in Researcher Workbench 2.0. You may also access files using command-line tools (e.g., gsutil) from supported analysis environments such as JupyterLab. To learn more about storage in Researcher Workbench 2.0, please review this Office Hours session.

Note: Following workspace migration, there may be a brief delay before resources appear. Please allow up to 30 minutes for content to populate in the Google Cloud Storage (GCS) bucket, and wait at least 30 minutes before creating an app environment in the migrated workspace.

Update Code and Re‑Create Analysis Objects 

After migration, some changes may be required before resuming analysis in Researcher Workbench 2.0. These changes are expected due to differences in tooling, data references, and environment setup between legacy Workbench and 2.0.

Helpful Tips:

Some analysis tools and features may become available at different times in Researcher Workbench 2.0. If a tool you previously used is not yet available, refer to the Featured Workspaces for recommended alternatives or updated workflows.

Consider Deleting Your Legacy Workspace

After migration, your workspace will still exist in Researcher Workbench 1.0 until the legacy platform is retired. While you may continue editing your legacy workspace, consider the following:

  • Changes made to the workspace after migration will not automatically sync to Researcher Workbench 2.0.
  • To reflect any updates made in the legacy workspace after migration to Researcher Workbench 2.0, you must return to the legacy workspace and re‑sync the files for migration. Note: Re-syncing a previously migrated workspace will overwrite the files that were migrated earlier.
  • You will continue to incur storage costs for legacy Workbench workspaces until they are deleted.

Recommendation: Once you have confirmed your work is complete and functioning in Researcher Workbench 2.0, delete the corresponding Researcher Workbench 1.0 workspace to avoid unnecessary storage costs. We highly recommend continuing analysis in Researcher Workbench 2.0 after a workspace has been migrated to prevent file override issues.

 

Step 4: Validation — Completion Checklist

Before fully transitioning your work to Researcher Workbench 2.0, confirm that you have

  • Opened and reviewed the migrated workspace in Researcher Workbench 2.0
  • Verified that all expected files are present
  • Updated SQL queries or code where required
  • Recreated cohorts or datasets using the Data Explorer
  • Confirmed your analysis runs successfully in Researcher Workbench 2.0

Once these steps are complete, you can continue your research in Researcher Workbench 2.0.

What Happens If You Do Not Migrate a Workspace

Workspaces that are not manually migrated by June 30th will be archived through a system‑led archival process. Archived workspaces are not active for analysis but may be recovered during the retention period. More information on this process will be provided soon. 

Recommendation and Resources

If you plan to continue working with a workspace, we strongly recommend migrating it to Researcher Workbench 2.0. Migration ensures immediate access, avoids delays associated with restoration, and provides the most seamless transition to the new platform.

Workspace Status
Migrated Workspace Archived Workspace Deleted Workspace
Workspace availability ✅ Fully active and available for analysis ➖ Not active for analysis ❌ Permanently removed
Files in the workspace bucket ✅ Copied to Researcher Workbench 2.0 Moved to archival storage ❌ Permanently deleted
Persistent disk files ❌ Not migrated (move to bucket pre-migration) ❌ Not archived ❌ Permanently deleted
Cohorts, datasets, concept sets ❌ Not migrated (must be recreated) ❌ Not archived ❌ Permanently deleted
Metadata ✅ Preserved ✅ Preserved ❌ Not Preserved
Recovery ➖ N/A - workspace remains active ✅ Available during retention period ❌ No
Retention period Ongoing TBD ❌ None
Costs Standard Researcher Workbench 2.0 storage and compute costs TBD ❌ No ongoing costs
Recommended for Active, ongoing research Workspaces not selected for active migration Work that is no longer needed

Additional Resources

The resources below provide step-by-step guidance, troubleshooting support, and opportunities to learn more about Researcher Workbench 2.0 during and after workspace migration.


Researcher Workbench 2.0 

Featured and Tutorial Workspaces

Workspace and Storage Management

Support and Help

Was this article helpful?

0 out of 4 found this helpful

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.