2.6. Parameter References#

In a previous example, we extracted a file using the “tar” program. However, that example was very limited because it assumed that the file we were interested in was called “hello.txt”, and this was written into the .cwl file. This is not the best way to do this, as the “hello.txt” filename may vary or be dependent on the input file(s) used. To avoid this we can specify the name of the file we want in the job parameters file (.yml). In this example, you will see how to reference the value of input parameters dynamically from other fields, which will allow us to then specify the name of the file to extract.

tar-param.cwl#
#!/usr/bin/env cwl-runner

cwlVersion: v1.0
class: CommandLineTool
baseCommand: [tar, --extract]
inputs:
  tarfile:
    type: File
    inputBinding:
      prefix: --file
  extractfile:
    type: string
    inputBinding:
      position: 1
outputs:
  extracted_file:
    type: File
    outputBinding:
      glob: $(inputs.extractfile)
tar-param-job.yml#
tarfile:
  class: File
  path: hello.tar
extractfile: goodbye.txt

Create your input files and invoke cwltool with the tool description and the input object on the command line:

$ rm hello.tar || true && touch goodbye.txt && tar -cvf hello.tar goodbye.txt

$ cwltool tar-param.cwl tar-param-job.yml
INFO /opt/hostedtoolcache/Python/3.9.13/x64/bin/cwltool 3.1.20220913185150
INFO Resolved 'tar-param.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/parameter-references/tar-param.cwl'
INFO [job tar-param.cwl] /tmp/z17wppbm$ tar \
    --extract \
    --file \
    /tmp/csko_w0d/stg2575b482-83d0-4414-a805-ac69c4530c28/hello.tar \
    goodbye.txt
INFO [job tar-param.cwl] completed success
{
    "extracted_file": {
        "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/parameter-references/goodbye.txt",
        "basename": "goodbye.txt",
        "class": "File",
        "checksum": "sha1$da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "size": 0,
        "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/parameter-references/goodbye.txt"
    }
}
INFO Final process status is success

Certain fields permit parameter references which are enclosed in $(...). These are evaluated and replaced with value being referenced.

outputs:
  extracted_out:
    type: File
    outputBinding:
      glob: $(inputs.extractfile)

References are written using a subset of Javascript syntax. In this example, $(inputs.extractfile), $(inputs["extractfile"]), and $(inputs['extractfile']) are equivalent.

The value of the “inputs” variable is the input object provided when the CWL tool was invoked.

Note that because File parameters are objects, to get the path to an input file you must reference the path field on a file object; to reference the path to the tar file in the above example you would write $(inputs.tarfile.path).

Where are parameter references allowed?

You can only use parameter references in certain fields. These are: