Importing a workflow and its configuration file from Dockstore into Terra

Liz Kiernan
  • Updated


Dockstore is a GA4GH-compliant, open-source platform for sharing Docker-based tools, such as Terra-compatible workflows written in the Worflow Description Language (WDL). 

At this time, only Dockstore workflows can be imported to Terra. Dockstore tools cannot be imported.

1. Access and select a Dockstore workflow from Terra

1.1. From inside your workspace, go to the Workflows tab and select "Find a Workflow" (left side)

1.2. At the bottom of the new window, under "Find Additional Workflows", select the Dockstore option. This will redirect you to the Dockstore website (you will no longer be in the Terra platform).


1.3. At the top of the Dockstore web page, select "Organizations". From the new page, you will see a list of organizations, such as TOPMed and NHLBI BioData Catalyst, that maintain Dockstore-supported tools and workflows. 

1.4. Click on the icon for the organization that hosts the workflow of interest. You will be redirected to a list of relevant workflows.

BioData Catalyst instructions

BioData Catalysis users will select TOPMed as the organization for BDC-specific workflows

1.5. For this tutorial's example, select the "TOPMed Alignment Workflow".  Then choose the WDL version of the workflow: "". 

This will open a page (see below) where you can find out more information about the workflow, including the available versions. 



If you check the "Versions" tab, you will see that the default version is already selected. If you need a different version, you can select it from this tab.  

You can view and download the main WDL workflow in the "Files" tab.

1.6. Use JSON (parameter) files for testing WDLs

You can also find a test JSON (parameter) file which lists the file locations and attributes for testing the workflow. To learn more, read about JSON files in the Terra knowledge base.


From the "Files" tab, select the "Test Parameter Files" sub-tab. Select the download icon to download the JSON file (we'll use this JSON file in the next section).

2. Import the workflow and JSON parameter file into Terra

2.1. Locate the "Launch with" icon at the bottom right of the Dockstore workflow page, and select the "Terra" option.  BioData Catalyst users can select the NHLBI BioData Catalyst option to go to the BioData Catalyst Terra platform.


Note that on the redirect page, there is a standard warning about Dockstore files displayed for all Dockstore WDL exports. 


2.2. Choose a Terra destination workspace or select "Create New". You will be redirected from the Dockstore platform back into the Terra platform, into the workflow "inputs" tab. 


2.3. To upload the JSON file you downloaded from Dockstore in Section 1, select the "upload json" 
2.4. Select Save

3. Additional workflow resources

To learn about more workflows and JSON files, see these resources in the Terra knowledge base:

  1. Getting workflows up and running faster with a JSON file
  2. Getting started running workflows
  3. Updating workflows to the latest version

You can also get started running a workflow in Terra by using the Workflows_QuickStart workspace. 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.