How to import a workflow and its parameter file from Dockstore into Terra

Updated November 10, 2022 13:41

Dockstore is a GA4GH-compliant, open-source platform for sharing Docker-based tools, such as Terra-compatible workflows written in the Workflow Description Language (WDL). Read on for step-by-step instructions for importing a workflow and its JSON setup file from Dockstore to your Terra workspace.

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

Step 1. Find a Dockstore workflow

1.1. Go to dockstore.org and click the Search icon at the top.

Or, from inside your workspace, go to the Workflows tab and select Find a Workflow (left side). 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.2. There are a number of different ways to browse for workflows, including filtering by organization or using a text search (click on Advanced Search in the left column). Make sure you select WDL under the language filter.

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.

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

1.3. Select a workflow of interest by clicking on the link in the Name column.

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

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

You can view the main WDL workflow in the "Files" tab (select the Descriptor Files option).

1.4. Download the parameter file (JSON) for testing

You can find a test parameter file (in JSON format) that lists the file locations and attributes for testing the workflow in the Test Parameter Files subtab (under Files).

Select the download icon (at the top-right corner) to download the JSON file.

To learn more, see Getting workflows up and running faster with a JSON file in Terra Support.

Step 2. Import the workflow and parameter file into Terra

2.1. Locate the Launch with widget at the top right of the Dockstore workflow page, and select the platform option.

Import-a-workflow-from-Dockstore_Launch-in-Terra_Screen_shot.png

Which Terra platform is for you?Select the AnVIL option to go to the AnVIL Terra platform or the NHLBI BioData Catalyst option to go to the BioData Catalyst Terra platform. Both AnVIL and BDC use Terra under the hood so all three options have the same functionality: they all go to Terra, but with small differences.

Note: On the redirect page, there is a standard warning about Dockstore files. This is displayed for all Dockstore WDL exports and is nothing to worry about.

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.