Set suggested input values for CWL v1.x apps

On this page, you will learn how to set suggested input values for your CWL v1.x app. Suggested values are predefined input values for inputs in an app, usually configured for commonly used input files such as reference genomes or other commonly used input values. When you run an app that has suggested input values configured for at least one of its file inputs, you are prompted whether to actually set those values as inputs on their respective input ports, which is done in a single click of a button. 

To configure your CWL v1.x app to use suggested files, you will have to make slight modifications to the app's CWL code, as follows: 

1. Navigate to a project on the CGC.
2. Open the Apps tab.
3. Click the name of the app for which you want to set suggested input files. You can now see app details.
4. In the top-right corner click Edit. Depending on whether you are editing a tool or workflow, the Tool Editor or Workflow Editor opens.
5. Click the Code tab. You can now see the CWL code of the app.
6. Find the inputs list in the app's CWL code. Each of the items in the list represents one of the app's inputs. 

Once you have reached the app's CWL code, continue by setting suggested input files or non-file values.

Set suggested input files 

To be able to set a file as suggested for an app's input port, you have to upload it to the CGC first, or use a file that is available in Public Reference Files or Public Test Files galleries. When you execute an app that has suggested files configured for at least one of its input ports, the files are copied to the execution project if they are not already present in that project or in one of your other projects. Note that only the root directory of the execution project is checked when verifying whether a suggested file already exists in that project. The user who is running the app needs Copy access in the project where the suggested file is stored. All users have Copy access for the Public Reference Files and Public Test Files galleries, so we suggest using these files when possible. 

When you find the file input for which you want to configure a suggested input file, add the code in the following format to it:

"sbg:suggestedValue": {
                "class": "File",
                "path": "<file-id>",
                "name": "<file-name>"
            },

To get the ID of a file, click the file name in the list under the Files tab in a project and copy the file ID from the URL. To get the ID via the API, you can list files in a project or folder.

For example, if configuring the Homo sapiens reference FASTA file for the hg19 assembly as a suggested input file, the code above with actual values would be:

"sbg:suggestedValue": {
                "class": "File",
                "path": "5772b6df507c1752674486ee",
                "name": "ucsc.hg19.fasta"
            },

This is what the code for the whole input in the inputs section would look like when a suggested file is added (the code has been truncated for brevity):

"inputs": [
...
        {
            "sbg:category": "File inputs",
            "sbg:suggestedValue": {
                "class": "File",
                "path": "5772b6df507c1752674486ee",
                "name": "ucsc.hg19.fasta"
            },
            "id": "in_reference",
            "type": "File?",
            "inputBinding": {
                "prefix": "--reference",
                "shellQuote": false,
                "position": 11
            },
            "label": "Reference file",
            "doc": "Reference file. This file is used for compression/decompression of CRAM files. Please provide reference file when using CRAM input/output file.",
            "sbg:fileTypes": "FASTA, FASTA.GZ, FASTA.BGZF, GZ, BGZF"
        },
...
]

Providing secondary files along with suggested files

As some kinds of files that are often set as suggested require secondary files, this is done by adding the secondaryFiles array in the sbg:suggestedValue object, as follows:

"sbg:suggestedValue": {
    "class": "File",
     "path": "5772b6df507c1752674486ee",
     "name": "ucsc.hg19.fasta",
     "secondaryFiles": [
         {
             "class": "File",
             "path": "578cf94a507c17681a3117e8",
             "name": "ucsc.hg19.fasta.fai"
         },
         {
             "class": "File",
             "path": "5c9ce4737369c402ad8a3c41",
             "name": "ucsc.hg19.dict"
          }
     ]
},

Each of the secondary file elements has the same structure as standard suggested files, so the values you need to provide are file ID (entered as the value for the path key) and file name. Secondary files will also be copied to the execution project unless they already exist at the root of that project.

Set suggested input values for non-file inputs 

Suggested input values can also be configured for all types of non-file inputs and entered in the CWL code as simple key:value pairs, where the key is sbg:suggestedValue, same as for file inputs. Some examples of suggested non-file input values are:

• “sbg:suggestedValue”: true
• “sbg:suggestedValue”: “string value”
• “sbg:suggestedValue”: [1, 2, 3]

In the CWL code, the key:value pair is placed inside the corresponding input port, as follows:

{
    "sbg:category": "Config Inputs",
  	"sbg:suggestedValue": "rnaseq",
    "id": "sort_by_tag",
    "type": "string?",
    "inputBinding": {
        "prefix": "-t",
        "shellQuote": false,
        "position": 5
        },
     "label": "Sort by value of tag",
     "doc": "Sort first by the value in the alignment tag, then by position or name (if also using -n)."
},