protocol.yml field reference

Overview

protocol.yml is the declarative file that defines a protocol: protocolSchema: v3 in standard YAML, replacing the deprecated protocol.json + script.js pair (see Legacy v2 format below). A protocol has no code of its own — it lists steps, each of which invokes an already-published task-script function, and can declare pipeline-facing config and author-set constants that steps and expressions read from.

protocolSchema: "v3"
name: "Example Protocol"
description: "This is just to show a basic protocol.yml file"

config:
  idsFileCategory:
    label: "IDS File Category"
    description: "Optional File Category"
    type: "string"
    required: false
    default: "IDS"

steps:
  - id: raw-to-ids
    task:
      namespace: common
      slug: akta-raw-to-ids
      version: v3.1.6
      function: akta-raw-to-ids
    input:
      input_file_pointer: $( workflow.inputFile )
      ids_file_category: $( config.idsFileCategory )

For the $( ... ) expression language itself — contexts and functions — see Expressions.

protocolSchema

Required. Must be exactly the string "v3". This indicates the file uses the v3 schema; a future JSON-encoded form of this schema is possible but not currently supported.

Manifest fields

All of the following are top-level in protocol.yml, optional, and mirror the corresponding fields in the protocol’s manifest.json (see Repo structure):

Field	Type	Notes
type	string	Must be "protocol"
namespace	string	common, or a string starting with client- or private-
version	string	vMAJOR.MINOR.PATCH
slug	string	The protocol’s identifier
name	string	Display name
description	string	Short description
catalog_keys	list of strings	Deprecated in favor of requirements in manifest.json; still accepted
labels	list of {name, value} objects	See the reserved-name list in Repo structure

ts-cli only warns, and does not fail the build, if a value here disagrees with the same field in manifest.json — keep them in sync manually.

config

Optional. An object mapping a config ID to a config object. Each ID must be unique so it can be referenced from steps or from an expression. Config objects cannot themselves contain expressions.

config:
  numberConfig:
    label: "Enter a Number"
    description: "This number will be used by the task scripts"
    type: number
    default: 9000
  secretExample:
    label: "ELN Password"
    description: "The password to push data to some ELN"
    type: secret

config.<config_id>.label

Required. String. The label rendered for this config in the TDP pipeline configuration UI.

config.<config_id>.type

Required. One of number | string | boolean | secret | object | array. Determines how the UI renders the field and how the value is passed to the workflow. array was added in TDP v4.4.

config.<config_id>.description

Optional string, rendered in the pipeline configuration UI.

config.<config_id>.required

Optional boolean, defaults to false. Enforced both in the UI and at workflow run-time.

Important

A config with required: false and no default still produces the key at run time — it arrives at the task script as null (None in Python). Either give it a default or have the task script handle a missing value explicitly.

config.<config_id>.default

Optional. Must match the config’s type. Cannot contain expressions. Used when the user hasn’t set a value via the UI.

config.<config_id>.component (added in TDP v4.3.2)

Optional object. Requests a specific UI widget for this config. This is only a request — the UI falls back to the default input for the config’s type if the requested component isn’t implemented. As of this writing, only select is actually wired up in the TDP UI; the rest are accepted by the schema and silently ignored by the UI.

component.type	Shape	Supported in UI?
select	{type: "select", options: [{label, value}, ...]}	Yes
multiselect	{type: "multiselect", options: [{label, value}, ...]}	No
textarea	{type: "textarea", placeholder?}	No
slider	{type: "slider", min, max, step?}	No
checkbox	{type: "checkbox"}	No
editor	{type: "editor", language?}	No

component:
  type: select
  options:
    - label: "Option A"
      value: a

config.<config_id>.schema (added in TDP v4.4.0)

Optional. Any valid JSON Schema Draft 2020-12 object. Requests that the pipeline configuration value be validated against this schema — but TDP does not currently enforce it. Don’t present it to an author as a working validation mechanism.

constants

Optional. An object mapping a constant ID to any value, so a protocol can define a value once instead of repeating it. Each ID must be unique across constants so it can be referenced from steps or other constants. Circular dependencies between constants are detected and rejected.

Constants may contain expressions, but those expressions have no steps context — nothing has run yet when constants are evaluated.

constants:
  REMOTE_PORT: 8080
  REMOTE_URL: "http://example.com"
  VALID_VALUES:
    - 80
    - 443
    - $( constants.REMOTE_PORT )
  CONFIG_OBJECT:
    url: $( constants.REMOTE_URL )
    ports: $( constants.VALID_VALUES )

steps

Required. A list of step objects, each of which invokes a task-script function.

steps:
  - id: stepOne
    task:
      namespace: common
      slug: raw-to-ids
      version: v1.0.0
      function: main
    input:
      input_file_pointer: $( workflow.inputFile )
  - task:
      namespace: common
      slug: push-to-eln
      version: v2.1.0
      function: "push-it"
    input:
      ids_file: $( steps.stepOne.output )
    options:
      timeoutInSec: $( config.pushToElnTimeout )

steps[*].id

Optional string. A unique identifier for the step, so later steps and expressions can address it by name instead of by list index. Always give a step an id — see the accessor-form guidance in Expressions.

steps[*].if

Optional boolean or expression. The step runs only when this evaluates to true; otherwise its status becomes skipped. If omitted, the step always runs.

config:
  skip-chromatograms:
    label: Skip step 'Extract chromatogram data using the MassLynx SDK'
    description: >
      Boolean. Optional. Default is `False`. If `True`, this modifies the
      protocol to skip the step 'Extract chromatogram data using the MassLynx
      SDK'.
    type: boolean
    required: false
    default: false

steps:
  - id: extract-chromatogram-data-from-raw-zip
    if: $( not(config["skip-chromatograms"]) )
    description: Extract chromatogram data using the MassLynx SDK
    task:
      namespace: common
      slug: masslynx-windows
      version: v1.0.3
      function: main
    input:
      input_file_pointer: $( workflow.inputFile )

Note the bracket accessor config["skip-chromatograms"] — required because the config ID contains a hyphen. config is always an ID-keyed mapping, never a list.

steps[*].continueOnError

Optional boolean or expression. If the step’s task fails and this evaluates to true, the protocol continues running; otherwise the whole protocol fails when this step fails. Useful for running cleanup steps after a failure.

steps[*].description

Optional string, shown on the TDP UI.

steps[*].task

Required object with four required sub-fields:

Field	Notes
task.namespace	e.g. common
task.slug	e.g. akta-raw-to-ids
task.version	e.g. v3.1.6
task.function	Must match one of the functions[].slug values in that task script’s config.json — not the Python function name. Task scripts can expose multiple functions; this picks one.

steps[*].input

Optional, any type. Evaluated and passed directly as the task-script function’s input argument — its keys are exactly the parameter names the task script’s Python code reads. Can contain expressions.

steps[*].options

Optional object of runner overrides:

Field	Notes
options.memoryInMB	Overridable in the pipeline configuration UI
options.timeoutInSec	Step is marked failed if this is exceeded
options.customWindowsAMI (added TDP v4.2.3)	Runs the task on a specific Windows EC2 AMI (string or expression); the AMI must exist in the same AWS region as the target TDP
options.runInLambda (added TDP v4.4.0)	Boolean or expression

successWhen (added TDP v4.3.0)

Optional boolean or expression. Overrides the default rule that a workflow succeeds only if every step succeeds.

successWhen: $( or(steps.stepOne.isSuccess, steps.stepTwo.isSuccess) )

onFailed (added TDP v4.3.0)

Optional, any type. Overrides the output value of a failed workflow, for logging. Defaults to null when successWhen is used.

onFailed: $( coalesce(steps.stepOne.error, steps.stepTwo.error) )

constraints (added TDP v4.3.2–v4.4.0 — confirm against your target TDP version)

constraints:
  trigger:
    type: ["file", "scheduled"]   # or a single string, e.g. type: "scheduled"

The only valid constraints.trigger.type values are "file" and "scheduled", singly or as a list — this is verified directly against the shipped ts_protocol_virtual_machine compiler schema (z.enum(["file", "scheduled"])). If constraints is omitted, the trigger type defaults to ["file"] — a protocol without scheduled in its trigger types won’t appear in the pipeline editor’s protocol picker when a SCHEDULED trigger is selected.

Note

constraints is stripped out of the protocol.yml stored in S3 by the artifact builder and copied into build-record.json instead, for backward compatibility with older TDP versions (the schema protocol.yml is validated against has always been strict, so an older deployment would otherwise fail on an unrecognized field). What an author writes in constraints and what ships in the published protocol.yml therefore differ — this is expected, not a bug.

Legacy v2 format (recognition only)

Deprecated November 2023 — do not author new protocols this way, but recognize it when maintaining an older repo. A v2 protocol is protocol.json (a declarative step list, no $( ... ) expression language) plus an imperative script.js that calls workflow.runTask directly. Its config is a list of {slug, name, type, required} objects — unlike v3’s ID-keyed mapping, and not a shape to carry over into a new v3 file.