Creating or editing a new Workflow in Terra requires working in the Terra Workflow Repository. This article includes step-by step instructions on how to create, edit, and share or clone a workflow.
Option 1. Create a new workflow
Follow the step-by-step instructions below to create a workflow from scratch and upload to a Terra workspace. Scroll down (or click here) if you prefer to use scripting (FISS) to upload a method to the Terra Workflow Repository.
1.1. Navigate to the Workflow tab in your workspace and click on the Find a Workflow card.
1.2. From the popup, click on the Terra Workflow Repository card on the right.
1.3. You'll be redirected to the Terra Workflow Repository, where you can click on the blue button at the top right corner to Create New Workflow +.
Clicking the Create New Method.. + button will open up a popup with fillable fields to set up your new workflow.
1.4. Enter your Collection name* and the Workflow name, followed by your WDL (enter manually or with "Load from file..."). Workflow names can include letters, numbers, underscores, dashes, and periods.
Optional information
You can add documentation, a synopsis, and version comments, if it would be useful for findability/usability.
1.5. Press Upload (at the bottom right) once you've filled in all the information.
-
Collection name* acts like a folder containing workflow and workflow configs. For example, if
you add the workflow "ExampleNewWorkflow" to the Terra Workflow Repository under the
collection "SupportDocs", its identifier would be: SupportDocs/ExampleNewWorkflowMany choose to put their name and/or institution in the collection field. You can
label your collections however you see fit, provided the chosen collection name does not
already exist. Administrators may verify collection names, which, like verified Twitter accounts,
establish the authenticity of collections attached to specific organizations (e.g., Broad
Institute).You can permit others to use your collection. This is great for labs who have multiple
contributors but want people to find all of their workflows under the "Miller-lab", for
example.In this case, we may add the collection name "SupportDocs" to any workflows that we create
for the purpose of documents.Name is the name of the specific workflow you create. This can be any name as
long as it does not already exist. In this example, the workflow is called
"ExampleNewWorkflow"Documentation is where you can add information about the WDL and what it does. We
encourage developers to add descriptive information so if you share this
with another user, they can recognize the inputs and outputs as well as any other
required information they may need to run the workflow successfully.Version is a numerical value assigned to the WDL. From the WDL section, you can make edits directly to the script and each time you press Upload, you create a new version. You can add comments (how the version differs from previous versions) in the Version comment field.
1.6. Once you finish uploading, you'll be directed to your new workflow. You can Export to Workspace by clicking the blue button at the top right-hand corner.
1.7. Choose the destination workspace to export your workflow to. You'll be prompted to go to the destination workspace.
What to expect
You'll be redirected back to your Terra Workflows tab, where you should see your new workflow.
Prefer scripting? Use FISS to upload to the Terra Workflow Repository
The(FI)reCloud (S)ervice (S)elector is another way to upload workflows to the Workflow Repository using scripting rather than right in Terra. You can use it from your terminal, following the instructions below.
FISS still uses terminology from the old Broad Methods Repository.
- Method = Workflow
- Namespace = Collection
- Snapshot = Version
1. Install FISS. You'll find instructions to do this in the readme of the FISS repo https://github.com/broadinstitute/fiss.
2. To see the command line format and optional variables, run fissfc meth_new
.
3. To put a WDL into a certain collection (namespace) with a method_name, run the following command:
fissfc meth_new -m method_name -n method_namespace -d path/to/local/wdl/file [-s desc of method] [-doc optional documentation] [-c optional snapshot comment]
-m
-n
and -d
inputs are required.Option 2: Edit a workflow in the Terra Workflow Repository
2.1. Open your workflow in the Terra Workflow Repository.
2.2. On the righthand side, you'll see a circle with three dots (where the orange arrow points in the screenshot below). Click this to expose a dropdown menu with options to save as, edit, delete version, and edit version permissions.
Making a workflow publicYou can select Edit version permissions to make a workflow public (see screenshot below).
2.2. Select Edit from the drop-down menu.
This should bring up the same screen used to create your workflow.
2.3. You can edit directly in the WDL section window.
The program automatically recognizes syntax errors when you press Upload. You can also change the snapshot comment depending on the changes that you made.
2.4. Press Create New Version.
You can see that there are now two versions. You do not need to export this workflow to Terra again. Just go to the Workflow tab to toggle between the snapshots when you click into the workflow.
Option 3: Share or clone a workflow
You can duplicate (clone) a workflow within your workspace or export to a new workspace following these steps:
3.1. Go to the Workflows tab of your Terra Workspace.
3.2. Click the three button icon for the workflow you want to share.
3.3. Select Duplicate to clone the workflow within the workspace or select Copy to Another Workspace to copy (clone) to a different workspace.