Defining parameters (arguments)

For Shell script/Docker workflows

When creating your workflow, you will see a section for Arguments to the right of your script. While in a draft state, you can add/remove arguments from this section. For each argument, we will provide fields for the following details:

• Name: Provide a name for your argument. When launching the analysis for a sample via the API, you can pass this name and its value. To access the argument in your script, we will prepend ARGS_ to the name, and we will capitalize the name. For instance, if you named your argument your_argument_1, you can access this in the script as $ARGS_YOUR_ARGUMENT_1.
• Type: Choose from a dropdown menu for the value type, such as boolean, number, integer, regex, string.
• Required: Check the box to determine if this argument is a required argument. If you check the box, you must provide a value at the time of launch.
• Description: An optional field to provide details on what this argument is for.

For Nextflow workflows

Nextflow workflows use the nextflow_schema.json file, which must be stored in the root directory of your GitHub repository, to define the parameters that will be used by the workflow. These arguments will be visible on the workflow edit/details page, where you can additionally set whether the argument is required or not.

To access the argument in your script, we will prepend ARGS_ to the name, and we will capitalize the name. For instance, if you named your argument your_argument_1, you can access this in the script as $ARGS_YOUR_ARGUMENT_1.

For Nextflow workflows, your argument values will be written to a file named input_params.json, which you will pass to your nextflow run command, such as:

nextflow run "${REPOSITORY_DIR}/main.nf" \
  -params-file input_params.json \
  --outdir output-$OCX_ANALYSIS_UUID 

Setting Argument Values at Launch

⏯️

Setting Required Arguments

Any parameters that are marked as required must be passed when launching the workflow. If required arguments have default values, these default values will automatically be populated in the web app, but they are not assumed when launching via the API, and must be provided, even if default values are being used.

To override the default parameters for a workflow run, or to set values for parameters that do not have defaults, you can:

1. Pass the values in the confirmation screen when launching via the web app
2. If launching the workflow via API, you can provide the arguments directly in the command, or store them in a .json file. For instance, if you saved the below as my_workflow_arguments.json:

{
    "sample":"the UUID of the sample you want to run the analysis on",
    "job_args": {
      	"your_argument_1": "arg_1_value",
        "your_argument_2": "arg_2_value",
    }
}

• then you can run the workflow, with the above arguments on the sample provided in the JSON, with the below command

curl -u $ONE_CODEX_API_KEY: -H "Content-Type: application/json" -d @my_workflow_arguments.json -X POST https://app.onecodex.com/api/v1/jobs/[workflow_UUID]/run

• where $ONE_CODEX_API_KEY is your API key,
• workflow_UUID is the unique identifier for the workflow that you want to run on the sample

3. Alternatively, you can pass the arguments directly to the cURL command, such as:

curl -u $ONE_CODEX_API_KEY: -H "Content-Type: application/json" -d {"sample":"[sample_UUID]", "job_args":{"your_argument_1": "arg_1_value","your_argument_2": "arg_2_value",}} -X POST https://app.onecodex.com/api/v1/jobs/[workflow_UUID]/run