Create, edit, and share a new workflow

Sushma Chaluvadi

Creating or editing a new Workflow in Terra requires working in the Broad Methods 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 Broad Methods Repository. 

1.1. Navigate to the Workflow tab in your workspace and click on the Find a Workflow card.

alt

 

1.2. From the popup, click on the Broad Methods Repository at the bottom, under Find Additional Workflows.

1.3. You will be redirected to the Broad Methods Repository, where you can click on the blue button at the top right corner to Create New Method. +.

ScreenShot of the top of the the screen in the Broads Methods Repo with an input field fo filtering at the top left and a blue button for creating a new workflow at the top right

Clicking the Create New Method.. + button will open up a modal to set up your new workflow.

screenshot of the modal to set up a new workflow with fields for the namespace and workflow name at the top, the WDL code in the middle, documentation field with a blue edit button, and a synopsis and snapshot comment fireld at the bottom, with a blue upload button beneath everything

1.4. Enter your Namespace* and the Name of your new Workflow followed by your WDL (enter manually or with "Load from file..."). Workflow names can include letters, numbers, underscores, dashes, and periods.

1.5. Press Upload once you've filled in all the information.

a screen capture for the process described above in steps 1.2 through 1.5

  • Namespace* acts like a folder containing workflow and workflow configs. For example, if
    you add the workflow "ExampleNewWorkflow" to the Broad Methods Repository under the
    namespace "SupportDocs", its identifier would be: SupportDocs/ExampleNewWorkflow

    Many analysts choose to put their name and/or institution in the namespace field. You can
    label your namespaces however you see fit, provided the chosen namespace does not
    already exist. Administrators may verify namespaces, which like verified Twitter accounts,
    establish the authenticity of namespaces attached to specific organizations (e.g., Broad
    Institute).

    You can permit others to use your namespace. This is great for labs who have multiple
    contributors but want people to find all of their methods under the "Miller-lab", for
    example.

    In this case, we may add the namespace "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.

    Snapshot is a numerical value assigned to the WDL similar to a versioning system. From
    the WDL section, you can make edits directly to the script and each time you press
    Upload, you create a new Snapshot. 

1.6. Once you finish uploading, you'll be directed to your new workflow. You can Export to Workspace from the top right-hand corner:

screenshot of the new workflow screen with the method name at the far left, the snapshot number '1' in the middle, and a blue export to workspace button on the right

1.7. The configuration lets you set inputs and save them to use again and again. You can select a configuration if one already exists or use a blank configuration.

screenshot of select method configuration portion of the workflow page with a blank field to filter a note that you don't have access to any published configurations for this method. THere is a blue use blank configuration button and a greyed out use selected configurayion button at the bottom right.

1.8. Choose the destination workspace. This is the Terra workspace to which you want to export your Workflow. You'll be prompted to go to the destination workspace, which will redirect you back to your Terra Workflows tab, where you should see your new workflow.

screenshot of Export ExampleNewWorkflow to workspace popup with fields for the workflow name - ExampleNew Workflow, the root entity type - participant - and the destination workspace - workshop-temp/test1 and a blue export to workspace button at the bottom right

Prefer scripting? Use FISS to upload to the Methods Repository

The(FI)reCloud (S)ervice (S)elector is another way to upload workflows to the Method Repository using scripting rather than right in Terra. You can use it from your terminal, following the instructions below. 

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 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] 
Note that the -m -n and -d inputs are required.

Option 2: Edit a workflow in the Broad Methods Repository

2.1. Open your workflow in the Broad Methods Repository (Summary tab). You'll see buttons and icons on the left for changing permissions, as well as editing, cloning or redacting the workflow.

Screenshot of the workflow summary tab in the Broad Methods Repository for the method SupportDocs/ExampleNewWorkflow, snapshot 1 and a blue export to workpace button at the right.

2.2. Press Edit from the left-hand bar. 
This should bring up the same modal used to create your workflow:

screenshot of create workflow screen with fields for the workspace namespace and name and an editable field with the WDL code

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 Save as New Snapshot.
You can see that there are now 2 Snapshots. 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.
screenshot closeup of the snapshot dropdown with 1 and 2 next to the SupportDocs/ExamplenewWorkflow method

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.

screenshot of the three-dot action item at the bottom right of the SampleWorkflow card with options to copy to another workspace, duplicate, or delete the workflow.

3.3. Select Duplicate to clone the workflow within the workspace or select Copy to Another Workspace to copy (clone) to a different workspace. 

 

Was this article helpful?

Comments

1 comment

Please sign in to leave a comment.