ToolJig: A simple approach to building Common Workflow Language tool descriptions and workflows


Image credit

The Common Workflow Language (CWL) is an open specification for describing command-line tools and workflows. CWL documents are used in many scientific disciplines to ensure that tools and workflows can be executed in a manner that is portable across workflow engines and computer systems. ToolJig facilitates creation of CWL tool descriptions, workflows, and input-object files for those tools. This video provides insight about ToolJig. This portion of ToolJig focuses on building tool descriptions. Use this app if you wish to create workflows.

Tool descriptions created in ToolJig are compatible with v1.2 (or 1.0 or 1.1) of the CWL specification. You can see some example CWL tool descriptions here. Our goal is support common use cases for research analyses. However, some options within the CWL specification are not supported; users should consult the specification if they wish to use other available features.

This app was created by the Piccolo lab. You can read our paper here. We are open to your feedback! Please submit an issue if you would like to report a bug or request a feature.

Upload existing file (optional):

If you previously created a CWL tool description using ToolJig, you can upload it and then edit the information below. (Uploading an existing file may not work for CWL files that were not created using alternative means.) If you do not need to edit an existing CWL file, skip this step.

This section enables you to create a CWL tool description. Please fill in the information as requested below. Required field = *.

Specify basics*:

This identifier must contain only letters, numbers, and underscores. This identifier will be used within the name of the CWL document that is generated. Show/hide example.
This description will inform tool users about its purpose and function. Show/hide example.
This optional description can provide more detailed documentation about the tool. Show/hide example.
A Dockerfile provides instructions for building a Docker image, which can be used as the operating-system environment for the tool. This article describes what Dockerfiles are and how to create them. Show/hide example.
This is optional. Specifying the author's name is helpful to others who may use the tool.
This is optional. Specifying the author's ORCID identifier enables others who may use the tool to obtain more information about the author. Show/hide example.
Please select a software license that applies to this CWL document. This will indicate conditions under which others can use the document. Details about these licenses and a more complete list can be found here.

Please correct the following error(s):

  • {{ error }}

Manage inputs*:

In this section, you can manage inputs. These are arguments that will be passed to the command-line tool. You must specify at least one regular input (string, int, or File). Technically, an "Output File" is not an input. However, when creating a CWL tool description, you can specify an input that is the name of an output file that the tool will create; then you must specify a corresponding output so the file will be collected after the tool executes. To make that simpler, we provide an "Output File" option that takes care of both of these steps. Show/hide example.

Please specify the file format (optional). These formats are from the EDAM Ontology and apply to bioinformatics tools. If the format is not specified in the list, please contact us.

Please correct the following error(s):

  • {{ error }}

Here you can edit () or delete () inputs.

  1. {{ input.name }} - {{ input.type }}

Please correct the following error(s):

  • {{ error }}

Manage auxiliary files:

In this section, you can manage auxiliary files (optional). Auxiliary files are stored within the execution environment and thus can be used in the command template (see below). Auxiliary files often include analysis scripts or configuration files (in CWL tool descriptions, they are stored under InitialWorkDirRequirement). Show/hide example.

Please correct the following error(s):

  • {{ error }}

Here you can edit () or delete () auxiliary files.

  1. {{ aux.name }}

Specify command template*:

Here you specify a template for executing the tool at the command line within the execution environment. Each input must be referenced at least once in the command template. For example, if you had defined an input string called "my_string", you would reference it in the command template as $(inputs.my_string). You would follow a similar pattern for inputs that are integers or "output files." However, it is different for input files; the input object will have multiple attributes, and you must specify one of these. For example, if you had defined an input file called "my_file" and wanted to refer to the path of that file, you would specify it in the command template as $(inputs.my_file.path). Alternatively, if you wanted to refer only to the name of the file, you would use $(inputs.my_file.basename). Other attributes are available. Show/hide example.

Please correct the following error(s):

  • {{ error }}

Manage outputs*:

After a tool executes successfully, you can collect three kinds of output. Standard output typically consists of messages or data printed to the console. Standard error typically consists of errors, warnings, or diagnostic information printed to the console. In addition, many command-line tools generate new data files.

In this section, you can specify alternate names for the files that will store standard output and standard error.

Here you can specify any output files that will be generated by the tool and that you wish to collect after the tool executes. These are separate from any "Output Files" you may have declared in the Inputs section. Please enter a unique identifier and a file pattern that represents the output file that you wish to collect. The file pattern can include UNIX-like wildcard characters. If the file will always have the same name, you can just enter the name of that file. Alternatively, you can enter an expression that references the inputs. For example, if you had specified an input file named "bam_file" and wished to collect an output file of the same name, you would specify the output expression as $(inputs.bam_file.basename). The ".basename" portion refers to the name of the input file and excludes the rest of the path. Other properties can be found here.

(Show/hide example)
(Show/hide example)
(Show/hide example)
(Show/hide example)

Please specify the file format (optional). These formats are from the EDAM Ontology and apply to bioinformatics tools.

Please correct the following error(s):

  • {{ error }}

Here you can edit () or delete () outputs.

  1. {{ output.ID }}

Please correct the following error(s):

  • {{ error }}

CWL document:

At least one error (see above) must be addressed before the CWL document can be generated.


        
        

            

                
            

            

                ToolJig does not have a way to save your CWL file, so be sure to download it before you close the app. If you wish to edit the CWL file later, you can upload it back into ToolJig.
            

        


        


        
Create input-object file:


        Once you have created a valid CWL file, you can create an input-object file, which defines inputs that will be used when the tool is executed in one particular instance. The boxes below correspond to the inputs defined above.

        
        
        

        

            Please correct the following error(s):
            

            
        


        


        

            
        


        


        
Example command to execute the tool:


        
First, you must install cwltool and Docker Engine. Then you can execute the following command, assuming the CWL file and input-object file are in your current working directory (if not, modify the command to point to the locations of these files). Alternatively, you can execute the tool using a variety of other engines.