Support Files

Bundle transformations, defaults, and dependencies alongside your workflow files

Overview

When uploading a workflow version, you can include support files alongside your WDL files. Support files let you configure transformations, defaults, and dependencies as part of a single upload — no additional API calls or UI steps required.

Workbench recognizes support files by their filename extension:

Extension	Creates
*.defaults.json	Default parameter values
*.transformation.js	Input transformations
*.dependencies.json	Workflow dependencies

Any file that does not match one of these patterns is treated as a regular workflow file (e.g., WDL descriptors, imported tasks).

Support files work identically whether you upload through the UI (drag and drop or file picker) or the CLI (workflows create / workflows versions create).

Example

A typical workflow upload with support files might look like this:

my-variant-pipeline/
├── main.wdl
├── tasks/
│   └── align.wdl
├── production.defaults.json
├── production.provider-AWS.region-us-east-1.defaults.json
├── normalize.transformation.js
└── upstream.dependencies.json

When you upload this directory, Workbench will:

1. Store main.wdl and tasks/align.wdl as workflow descriptor files

2. Create a defaults entry named production with default parameter values

3. Create a second defaults entry named production scoped to AWS in us-east-1

4. Create a transformation named normalize

5. Create a dependency set named upstream

All of this happens in a single upload. If any support file fails validation, the entire upload is rolled back — no partial state is created.

---

Defaults

Defaults files provide pre-configured parameter values for a workflow version. They are useful for setting environment-specific values (such as reference genome paths, thread counts, or cloud provider settings) so users don't have to fill them in manually for every run.

Basic usage

Any file ending in .defaults.json is recognized as a defaults file. The portion before .defaults.json becomes the name.

Filename: production.defaults.json

{
  "threads": 8,
  "memory": "16GB",
  "reference_genome": "gs://my-bucket/references/hg38.fa"
}

This creates a defaults entry named production with the specified parameter values.

You can also wrap parameters in a values object — both formats are accepted:

{
  "values": {
    "threads": 8,
    "memory": "16GB"
  }
}

Selectors

Selectors let you scope defaults to specific execution environments. Add selector segments between the name and .defaults.json, using the format key-value:

<name>.<key-value>.<key-value>.defaults.json

The supported selector keys are:

Key	Description	Example
provider	Cloud provider	provider-AWS, provider-GCP
region	Cloud region	region-us-east-1, region-europe-west1
engine	Execution engine	engine-omics, engine-cromwell

Examples:

Filename	Name	Selector
prod.defaults.json	prod	(none — applies broadly)
prod.provider-AWS.defaults.json	prod	provider = AWS
prod.engine-omics.provider-AWS.region-us-east-1.defaults.json	prod	provider = AWS, region = us-east-1, engine = omics

Selector segments can appear in any order. Unknown selector keys are silently ignored, so existing uploads remain compatible as new keys are introduced.

Two defaults files with the same name and identical selectors will cause the upload to fail. Different selectors for the same name are allowed — this is how you create environment-specific overrides.

---

Transformations

Transformations are JavaScript functions that modify workflow inputs before execution. They are useful for normalizing user-provided values, injecting computed parameters, or adapting inputs for specific execution environments.

Basic usage

Any file ending in .transformation.js is recognized as a transformation. The portion before .transformation.js becomes the name.

Filename: normalize.transformation.js

function transform(params) {
  if (params.sample_id) {
    params.sample_id = params.sample_id.trim().toUpperCase();
  }
  return params;
}

This creates a transformation named normalize.

Transformation scripts are stored as-is. Workbench does not validate JavaScript syntax at upload time.

Ordered chains

When you need transformations to run in a specific sequence, prefix the filename with a number and a dash:

<order>-<name>.transformation.js

Examples:

Filename	Name	Order
normalize.transformation.js	normalize	(unordered)
1-validate.transformation.js	validate	1
2-normalize.transformation.js	normalize	2
03-enrich.transformation.js	enrich	3

Ordered transformations form a chain that executes in ascending numeric order. Unordered transformations are appended after any ordered chain.

Two transformations with the same name, or two transformations with the same order number, will cause the upload to fail.

---

Dependencies

Dependencies define prerequisite workflows that must complete before this workflow can run. They are useful for building multi-step analysis pipelines where one workflow's output feeds into another.

Basic usage

Any file ending in .dependencies.json is recognized as a dependencies file. The portion before .dependencies.json becomes the name.

Filename: upstream.dependencies.json

{
  "dependencies": [
    {
      "workflow_id": "alignment-pipeline",
      "workflow_version_id": "v2_0_0"
    }
  ]
}

This creates a dependency set named upstream that references the alignment-pipeline workflow.

Only one set of dependencies can exist for any given workflow version. Include a single .dependencies.json file per upload.

---

Version updates and copy-forward

When you upload a new workflow version, support file behavior depends on what you include in the upload:

• No support files of a given type included: The previous version's entries for that type are automatically carried forward. For example, uploading only a new main.wdl will preserve all defaults, transformations, and dependencies from the prior version.

• Any support file of a given type included: Copy-forward is disabled for that type, and only the files you upload are used. For example, including a single prod.defaults.json replaces all defaults from the prior version — not just the one named prod.

Copy-forward is all-or-nothing per type. You cannot selectively update one defaults entry while keeping others from a previous version — either include all the defaults files you want, or include none to carry everything forward.

This does not affect WDL descriptor files. Each version's WDL files are an immutable snapshot and are never copied from prior versions.

---

Troubleshooting

Error message	Cause
Multiple transformations named '<name>'	Two transformation files resolve to the same name
Multiple transformations with order '<n>'	Two transformation files share the same numeric order prefix
Multiple defaults with name '<name>' and identical selectors	Two defaults files have the same name and matching selector values
Multiple dependencies named '<name>'	Two dependencies files share the same name
Failed to parse defaults file '<filename>': ...	The JSON content of a defaults file is malformed
Failed to parse dependencies file '<filename>': ...	The JSON content of a dependencies file is malformed
Dependencies file '<filename>' missing required 'dependencies' field	The JSON is valid but missing the top-level dependencies array