WDL Best Practices

Best Practices

The following are some best practices for creating tools. As descriptor languages change, so should this document; feel free to provide suggestions and/or improvements.

In this tutorial, we will be using the same example from our getting started with WDL tutorial, dockstore-tool-bamstats.

Authorship Metadata

Dockstore parses metadata and allows it to be used in Dockstore search which helps others find your tool/workflow more easily. “Author” is one of the metadata fields that is searchable:

search-metadata

search-metadata

Additionally, metadata is displayed in the tool/workflow’s “Info” tab. The highlighted sections below will appear once metadata is added to the descriptor:

info-tab-metadata

info-tab-metadata

For all developers, we highly recommend the following minimal metadata for your tools and workflows.

This example includes author, email, and description metadata:

/Dockstore.wdl

version 1.0
task bamstats {
    input {
        File bam_input
        Int mem_gb
    }


    command {
        bash /usr/local/bin/bamstats ${mem_gb} ${bam_input}
    }

    output {
        File bamstats_report = "bamstats_report.zip"
    }

    runtime {
        docker: "quay.io/collaboratory/dockstore-tool-bamstats:1.25-6_1.0"
        memory: mem_gb + "GB"
    }

    meta {
        author: "Andrew Duncan"
        email: "Andrew.Duncan@oicr.on.ca"
        description: "![build_status](https://quay.io/repository/collaboratory/dockstore-tool-bamstats/status) A Docker container for the BAMStats command. See the [BAMStats](https://bamstats.sourceforge.net/) website for more information."
    }
}

workflow bamstatsWorkflow {
    input {
        File bam_input
        Int mem_gb
    }
    call bamstats { input: bam_input=bam_input, mem_gb=mem_gb }
}

This results in the tools’s Info Tab being populated like:

wdl-info-tab-metadata

wdl-info-tab-metadata

Sample Parameter Files

Below is an example of a parameter file for the example above. We encourage checking in working examples of parameter files for your tool/workflow. This allows others to quickly work with your tool/workflow, starting from a “known good” parameterization. Having at least one parameter file brings your tool/workflow one step closer to getting verified.

test.wdl.json

{
  "bamstatsWorkflow.bam_input": "NA12878.chrom20.ILLUMINA.bwa.CEU.low_coverage.20121211.bam",
  "bamstatsWorkflow.mem_gb": "4"
}

Now invoke dockstore with the workflow wrapper and the input object on the command line and ensure that it succeeds:

$ dockstore tool launch --local-entry wdl/bamqc.wdl --json test.wdl.json

...
Calling out to Cromwell to run your workflow
Executing: java -jar /Users/natalieperez/.dockstore/libraries/cromwell-44.jar run /Users/natalieperez/Projects/dockstore-tool-bamstats/Dockstore.wdl --inputs /var/folders/xq/7_kn047j4sb41bfb2_3nng4m0000gq/T/foo15775077532364354801json
...
Cromwell exit code: 0
Cromwell stdout:
...

Next Steps

At this juncture, you have completed all of the developer tutorials.

Please continue onwards with specific topics of interest via our Advanced Developer Topics or our End User Topics