Pipeline Guide

Input Parameters

To define inputs that will be used in a pipeline, you can use the Input Parameters circle located in the pipeline’s left sidebar menu.

Just like adding processes, you can drag and drop input parameters onto your pipeline workflow.
When you drag an input parameter, you will see a smaller orange circle representing the input parameter in the workspace:

input-green-circle

By using the pencil icon to the left of the circle, you can edit the name of the input parameter and define additional settings for it.

Input Parameter Options

Name
This is the name of the input parameter, which will be used to reference the parameter in the Nextflow file (for example, params.genome_build).
Make sure to use unique names for each input parameter within your pipeline to avoid conflicts.
Default value
You can specify a default value for the input parameter. This value will be auto-filled on the Run page and is useful when a commonly used value works for most runs.
Dropdown options
If you want the input parameter to appear as a dropdown menu on the Run page, you can define its options as a comma-separated list.
For example, for a yes/no parameter:
yes, no
Show Settings
- Enabling Show Settings displays a wrench button on the Run page for the connected process.
- This lets users access and modify specific settings for that process.
- If you want this wrench button to open settings for alternative processes, you can list their process names here. For example: map_STAR, map_RSEM will show settings for either the map_STAR or map_RSEM mapping processes.

Example – Run Page View

Here’s an example configuration of run_DEseq2 parameter:

input settings

and how the input row looks like on the Run page:

input-setting-run-page

Adding Global Pipeline Inputs Using the `nextflow.config` File

You can define global pipeline inputs in the nextflow.config file under the Advanced tab of a pipeline’s page.
These inputs will appear in the Inputs section on the Run page. To create an input parameter, use the following syntax:

params.variableName = defaultValue //* @dropdown @options:"option1, option2, option3"

Key points:

The variable name must start with params. (for example, params.genome_build).
defaultValue can be:
A string (with single or double quotes), e.g., "human_hg19"
A number (without quotes), e.g., 10
An empty string "" if you don’t want to set a default.
The @options annotation defines the dropdown options using a comma-separated list.

On the Run page, these parameters will be displayed in the Inputs section, and users will be prompted to select or enter values based on the defined options.

Example:

params.genome_build = ""  //* @dropdown @options:"human_hg19, mouse_mm10, custom"
params.run_STAR     = "no" //* @dropdown @options:"yes, no"

In this example:

genome_build is a dropdown with three options: human_hg19, mouse_mm10, and custom where no option is selected by default.
run_STAR is a yes/no dropdown with a default value of no.

Genome build selection

Global Pipeline Input Specifiers

You can control how global pipeline inputs are displayed and handled on the Run page by using special specifier tags in the nextflow.config file.

`@optional`

By default, inputs are treated as required. You can mark an input as optional using the @optional tag. Optional inputs may be left empty by the user.

params.a_input = "" //* @input @optional @description:"Input A for process"
params.b_input = "" //* @input @optional @description:"Input B for process"

`@file`

By default, inputs use a value modal (simple text/number entry). If you add the @file tag, the input will use the dataset-selection modal, allowing the user to select a dataset.

params.reads = "" //* @input @file @description:"Reads dataset for pipeline"

In this example, params.reads is defined as a file/dataset input. On the Run page, selecting this input opens a dataset-selection modal.

`@single_file`

If you add the @single_file tag, the input will use the single file modal, which allows users to upload a file via drag and drop or entering the full path of the file.

params.groups_file = "" //* @input @optional @single_file

This is useful for parameters that expect a single metadata or configuration file.

`@editor`

The @editor tag further extends @single_file by opening the single file modal with an embedded spreadsheet editor, letting users create or edit tabular metadata directly in the browser.

params.groups_file = "" //* @input @optional @single_file @editor:{ "default":[["sample_name","group"]], "collection_autofill":{"input_name":"reads", "column":"1"}, "type":"spreadsheet",  "filename":"metadata.tsv", "separator":"tab"} @description:"You can enter CSV/TSV content here."

In this example:

"default":[["sample_name","group"]] Sets the default header row of the spreadsheet to sample_name and group.
"collection_autofill":{"input_name":"reads", "column":"1"} Enables autofill: when the modal opens, Foundry automatically fills the first column ("column":"1") with sample names from the dataset selected in the reads input.
"type":"spreadsheet" Indicates that this editor should behave as a spreadsheet.
"filename":"metadata.tsv" Sets the default filename for the file generated by the editor.
"separator":"tab" Specifies the delimiter (here, a tab character) used when saving the file.

Together, @single_file + @editor provide a convenient way to define structured metadata (e.g., sample groups) directly in the UI.

Autoscaling Memory, CPU, and Time Limits

You can enable automatic resource scaling for your pipeline by setting the flags
$AUTOSCALE_MEMORY, $AUTOSCALE_CPU, and/or $AUTOSCALE_TIME to true in your nextflow.config file.

$AUTOSCALE_MEMORY = true
$AUTOSCALE_CPU    = true
$AUTOSCALE_TIME   = true

When these flags are enabled, the pipeline will dynamically adjust resource requests (memory, CPU, and/or time) in response to errors encountered during execution.

How it works

For each retry attempt that fails due to insufficient resources, the requested values are increased. For memory, this follows a pattern similar to:

requestedMemory = initialMemory * run_attempt

On the first attempt, the process uses the initial requested memory.
On the second attempt, memory is increased (for example, doubled relative to the first attempt).
On later attempts, the memory continues to scale with each run_attempt.

When $AUTOSCALE_CPU and/or $AUTOSCALE_TIME are enabled, a similar autoscaling behavior is applied to CPU and time limits, helping to:

Reduce failures related to resource constraints.
Improve robustness for jobs that occasionally require more resources than expected.

Autofill Feature for Pipeline Inputs

Via Foundry supports an autofill mechanism that lets you automatically set parameter values based on:

The hostname of the execution environment.
The user’s selected input values on the Run page.
A combination of both (dynamic autofill).

A. Autofill Based on Hostname

You can use the autofill feature to specify input parameters based on the hostname of the execution environment.

Syntax:

//* autofill
if ($HOSTNAME == "umassrc.org") {
    <input parameters>
}
//* autofill

$HOSTNAME is a Via Foundry–specific variable representing the hostname of the execution environment.
Replace "umassrc.org" with the actual hostname where you want these autofilled inputs to apply.
Inside the if block, define the input parameters that should be automatically filled when the pipeline runs on that hostname.

Example – Autofill a Parameter for a Specific Hostname

//* autofill
if ($HOSTNAME == "umassrc.org") {
    params.software_version = "0.32"
}
//* autofill

In this example, params.software_version will be set to 0.32 when the pipeline is executed on umassrc.org.

B. Autofill Based on Selected Input

You can also autofill parameters based on values selected by the user on the Run page.

Example – Autofill Species Based on Genome Build

params.genome_build = "" //* @dropdown @options:"mm10, hg38"

//* autofill
if (params.genome_build == "mm10") {
    params.species = "mouse"
} else if (params.genome_build == "hg38") {
    params.species = "human"
}
//* autofill

Here, params.genome_build is exposed as a dropdown with options mm10 and hg38.
Depending on the selection:
mm10 → params.species = "mouse"
hg38 → params.species = "human"

C. Dynamic Autofill

Dynamic autofill lets you set multiple related parameters that follow a naming pattern, based on both selected inputs and hostname.

You can define intermediate variables (for example, _species, _build, _share) and then construct final parameter values using those pieces.

A common pattern is:

if (params.variableName && $HOSTNAME) {
    <input parameters>
}

// or

if ($HOSTNAME) {
    <input parameters>
}

Example – Dynamic Autofill for Genome Paths

In the example below, params.genome and params.genomeIndexPath are autofilled based on params.genome_build and $HOSTNAME:

params.genome_build = "" //* @dropdown @options:"human_hg19, mouse_mm10"

def _species
def _build
def _share

//* autofill
if (params.genome_build == "human_hg19") {
    _species = "human"
    _build   = "hg19"
} else if (params.genome_build == "mouse_mm10") {
    _species = "mouse"
    _build   = "mm10"
}

if ($HOSTNAME == "umassmed.edu") {
    _share = "/share/genome_data"
} else if ($HOSTNAME == "umassrc.org") {
    _share = "/project/genome_data"
}

if (params.genome_build && $HOSTNAME) {
    params.genome          = "${_share}/${_species}/${_build}/${_build}.fa"
    params.genomeIndexPath = "${_share}/${_species}/${_build}/${_build}"
}

if ($HOSTNAME) {
    params.binFiles = "${_share}/bin"
}
//* autofill

This logic:

Sets species/build variables based on params.genome_build.
Sets a shared path (_share) variable based on $HOSTNAME.
Dynamically creates full paths for params.genome, params.genomeIndexPath, and params.binFiles based on the individual variables.

Autofill Feature for Pipeline Properties

You can also use the autofill feature to define executor properties in Via Foundry. This supports:

Hostname-independent defaults.
Hostname-dependent overrides.

Hostname-Independent Autofill

To define executor properties that are always applied, regardless of hostname:

//* autofill
<executor properties>
//* autofill

Hostname-Dependent Autofill

To override or extend executor properties for specific hostnames:

//* autofill
<executor properties>

if ($HOSTNAME == "umassrc.org") {
    <hostname dependent executor properties>
}
//* autofill

<executor properties> apply to all hostnames.
Inside the if ($HOSTNAME == "umassrc.org") block, you can add or override settings specifically for umassrc.org.

$HOSTNAME represents the selected hostname in the Run Environment.

Executor Properties

There are five executor properties you can autofill for Executor Settings for All Processes:

$TIME – Wall time
$CPU – Number of CPUs
$MEMORY – Memory
$QUEUE – Queue/partition
$EXEC_OPTIONS – Other executor options

You can set pipeline defaults using $HOSTNAME == "default":

//* autofill
if ($HOSTNAME == "default") {
    $MEMORY = 32
    $CPU    = 1
}

if ($HOSTNAME == "umassrc.org") {
    $TIME         = 3000
    $CPU          = 4
    $MEMORY       = 100
    $QUEUE        = "long"
    $EXEC_OPTIONS = '-E "file /home/mylab"'
}
//* autofill

Singularity / Docker Images

You can set default image for pipeline using following parameters. Foundry can autofill container-related properties as well:

$DOCKER_IMAGE
$DOCKER_OPTIONS
$SINGULARITY_IMAGE
$SINGULARITY_OPTIONS

These fields automatically fill the Image path and RunOptions settings for Docker and Singularity.

Example – Docker Image Autofill:

//* autofill
if ($HOSTNAME == "umassrc.org") {
    $DOCKER_IMAGE   = "docker://UMMS-Biocore/docker"
    $DOCKER_OPTIONS = "-v /export:/export"
}
//* autofill

Example – Singularity Image Autofill:

//* autofill
if ($HOSTNAME == "umassrc.org") {
    $SINGULARITY_IMAGE   = "shub://UMMS-Biocore/singularity"
    $SINGULARITY_OPTIONS = "--bind /project"
}
//* autofill

Using Both Docker and Singularity

If you define both Docker and Singularity settings, the Run page will be auto-filled based on the selected Container Type in Profile → Container Type (Docker or Singularity):

//* autofill
if ($HOSTNAME == "default") {
    $DOCKER_IMAGE      = "viascientific/rnaseq:1.0"
    $SINGULARITY_IMAGE = "https://galaxyweb.edu/pub/dnext_data/singularity/UMMS-Biocore-rna-seq-1.0.img"
}

if ($HOSTNAME == "umassrc.org") {
    $DOCKER_IMAGE      = "viascientific/rnaseq:1.0"
    $SINGULARITY_IMAGE = "https://galaxyweb.edu/pub/dnext_data/singularity/UMMS-Biocore-rna-seq-1.0.img"
}
//* autofill

Platform Tag

The platform tag allows you to isolate platform-dependent parameters in Via Foundry.

Parameters inside //* platform blocks are treated as platform-specific.
When exporting a pipeline, these platform-dependent parameters are not overwritten when re-imported on another platform.
This is useful for keeping site-specific settings (like queues, paths, and options) separate from shareable pipeline logic.

Example – Using the Platform Tag

//* autofill
if ($HOSTNAME == "default") {
    $MEMORY = 32
    $CPU    = 1
}
//* autofill

//* platform
if ($HOSTNAME == "umassrc.org") {
    $TIME         = 3000
    $CPU          = 4
    $MEMORY       = 100
    $QUEUE        = "long"
    $EXEC_OPTIONS = '-E "file /home/mylab"'
}
//* platform

In this example:

The default settings ($MEMORY = 32, $CPU = 1) are general pipeline defaults.
The platform block for umassrc.org defines site-specific executor settings that will not overwrite or conflict when the pipeline is imported into other environments.

Executor-Specific Nextflow Profiles (Auto-Enabled by Foundry)

Foundry can auto-enable an executor-specific Nextflow profile at runtime, based on the executor used for a run. Use this to isolate executor-dependent settings (for example, GPU-related overrides) in nextflow.config.

Profile names

Foundry looks for these profiles:

awsbatch → foundry_awsbatch
googlebatch → foundry_googlebatch
slurm → foundry_slurm
lsf → foundry_lsf
local → foundry_local

Precedence (when values conflict)

process directives > foundry_* profile > Run page Advanced / Run Environment defaults

Minimal example

profiles {
  foundry_awsbatch {
    process {
      withLabel: 'gpu' {
        // executor-specific overrides
      }
    }
  }
}

Setting a Specific Nextflow Version

If you want your pipeline to use a specific Nextflow version, you can set it in the nextflow.config file using the manifest.nextflowVersion field as a single line, for example:

For example:

manifest.nextflowVersion = "25.10.2"

Pipeline Guide

Input Parameters

Input Parameter Options

Adding Global Pipeline Inputs Using the nextflow.config File

Global Pipeline Input Specifiers

@optional

@file

@single_file

@editor

Autoscaling Memory, CPU, and Time Limits

How it works

Autofill Feature for Pipeline Inputs

A. Autofill Based on Hostname

B. Autofill Based on Selected Input

C. Dynamic Autofill

Autofill Feature for Pipeline Properties

Hostname-Independent Autofill

Hostname-Dependent Autofill

Executor Properties

Singularity / Docker Images

Platform Tag

Executor-Specific Nextflow Profiles (Auto-Enabled by Foundry)

Profile names

Precedence (when values conflict)

Minimal example

Setting a Specific Nextflow Version

Adding Global Pipeline Inputs Using the `nextflow.config` File

`@optional`

`@file`

`@single_file`

`@editor`