Naming & IDs

Clear, stable names keep projects reproducible and easy to automate.

Why It Matters

  • Used in commands: bpm template render <id> and bpm workflow run <id>.
  • Used in paths: many templates use ${ctx.project.name}/${ctx.template.id}/.
  • Used in lookups: publish keys become stable handles to outputs.

Types of Names

  • Projects (project.yaml:name): human label for the project; often appears in paths.
  • Stores (BRS id): the catalog identifier you add/activate.
  • Templates/Workflows (id): folder name under templates/ or workflows/ and the descriptor id.
  • Publish keys: names under publish: in template_config.yaml.

Simple Rules

  • Be filesystem‑safe: letters, numbers, - and _. No spaces or slashes.
  • Keep it short and stable: avoid frequent renames once shared/used.
  • Prefer lowercase for template/workflow ids: e.g., demux_bclconvert, nf_align.
  • Project names: allow digits/uppercase if you like (250903_TEST), but avoid spaces.
  • Publish keys: use snake_case and describe the artifact, e.g., fastq_dir, multiqc_report.

Template/Workflow IDs

  • Must match the folder and descriptor exactly.
    • Folder: templates/hello/
    • Descriptor: templates/hello/template_config.yaml with id: hello
  • Used by the CLI and context: ctx.template.id == 'hello'.
  • Changing an id requires renaming the folder and updating id in the descriptor (and any references).

Good ids

  • hello, demux_bclconvert, qc-multiqc, nf_align

Avoid

  • Demux BCL Convert (spaces)
  • align#1 (symbols)
  • ../../weird (path segments)
  • Extremely long names

Project Names

  • Set in project.yaml as name: and used in path templates by convention.
  • Examples: 250903_TEST, rna_seq_2024q3.
  • Avoid spaces; prefer _ or - as separators.

Store (BRS) IDs

  • Shown in bpm resource list and used for activation.
  • Keep short and unique, e.g., uka_gf_brs or UKA_GF_BRS (pick a style and stick to it).

Publish Keys

  • Keys under publish: identify outputs other steps/users will consume.
  • Make them short, stable, and specific; document their type/shape.
  • Examples: fastq_dir (dir), multiqc_report (file), samples_table (tsv).

Validation in BPM

  • BPM requires the descriptor id to equal the folder name; it does not impose a regex.
  • Filesystem‑unsafe characters may still break paths — follow the simple rules above.

Quick Checklist

  • No spaces; only letters, numbers, - and _.
  • Template/workflow id equals folder name and stays lowercase.
  • Publish keys are snake_case and documented.
  • Avoid renaming once published/used.