Workflow UI templates

RAFT browser tools can be customized by workflow-owned UI template files in the workflow configuration repository. These templates let workflow maintainers control what the manifest generator and report viewer show without requiring a RAFT release for every workflow-specific UI change.

Template locations

For a workflow configuration repository such as:

workflow-configs/lens/lens-human/lens-human-fastqs/

RAFT looks for manifest templates in this order:

lens.human.fastqs.manifest-ui.json
manifest-ui.json

RAFT looks for report templates in this order:

lens.human.fastqs.report-ui.json
report-ui.json

The input-specific filename is preferred. The generic filename is useful when the same UI behavior applies to every input mode for a workflow.

If no workflow-owned template is available, RAFT falls back to packaged generic defaults.

Manifest template

The manifest template controls manifest columns, sample types, workflow labels, and workflow-level sample requirements. RAFT also uses this file for CLI manifest validation when raft check-manifest can auto-detect a single workflow template from a project or when --manifest-ui-template is provided explicitly. The CLI uses columns[].required, columns[].allowed_values, and sample_types[].prefix/sample_types[].normal for structural checks, then applies additional cross-row checks that are not represented in the UI template.

A LENS-style example:

{
  "schema_version": "1.0",
  "name": "LENS manifest",
  "description": "Manifest requirements for LENS tumor antigen discovery.",
  "columns": [
    {"name": "Patient_Name", "label": "Patient name", "required": true},
    {"name": "Run_Name", "label": "Run name", "required": true},
    {"name": "Dataset", "label": "Dataset", "required": true},
    {"name": "File_Prefix", "label": "File prefix", "required": true},
    {
      "name": "Sequencing_Method",
      "label": "Sequencing method",
      "required": true,
      "allowed_values": ["WES", "WXS", "WGS", "RNA-Seq", "RNA"]
    },
    {
      "name": "Normal",
      "label": "Normal",
      "required": true,
      "allowed_values": ["TRUE", "FALSE"]
    },
    {"name": "Group", "label": "Group", "required": false},
    {"name": "Alleles", "label": "Alleles", "required": false}
  ],
  "sample_types": [
    {
      "id": "tumor_dna",
      "label": "Tumor DNA",
      "prefix": "ad-",
      "normal": false,
      "sequencing_method": "WES"
    },
    {
      "id": "normal_dna",
      "label": "Normal DNA",
      "prefix": "nd-",
      "normal": true,
      "sequencing_method": "WES"
    },
    {
      "id": "tumor_rna",
      "label": "Tumor RNA",
      "prefix": "ar-",
      "normal": false,
      "sequencing_method": "RNA-Seq"
    },
    {
      "id": "normal_rna",
      "label": "Normal RNA",
      "prefix": "nr-",
      "normal": true,
      "sequencing_method": "RNA-Seq"
    }
  ],
  "workflows": [
    {
      "value": "lens",
      "label": "LENS",
      "description": "Tumor antigen discovery from tumor DNA, normal DNA, and tumor RNA.",
      "requirements": {
        "normal_dna": true,
        "tumor_dna": true,
        "tumor_rna": true,
        "normal_rna": false
      }
    }
  ]
}

Manifest template fields

columns: Defines the manifest columns exported by the generator. Each entry should include name. label, required, description, and allowed_values are optional UI hints.
sample_types: Defines selectable sample types and their Run_Name prefixes. The id values should be stable machine-readable names. These IDs are also used in workflow requirements.
workflows: Defines workflow choices and sample requirements. Requirements are keyed by sample type id.

Report template

The report template controls the patient-level sections shown by the RAFT report viewer. RAFT keeps the standard patient sidebar, group navigation, and collapsible layout behavior. Workflow maintainers customize the main report sections, labels, renderer hints, input file patterns, controls, and optional table columns. Workflows do not need to produce pMHC data; QC-only and generic table-based reports are supported.

A minimal LENS-style example:

{
  "schema_version": "1.0",
  "name": "LENS report",
  "description": "Patient-level antigen report and QC review for LENS.",
  "bundle_format": "raft-report-bundle-v1",
  "layout": {
    "navigation": "patients",
    "group_navigation": true,
    "collapsible_sidebar": true
  },
  "sections": [
    {
      "id": "report",
      "label": "Report",
      "renderer": "lens_antigen_report",
      "source": "lens",
      "default": true,
      "patterns": ["*.report.tsv", "*report*.tsv"],
      "controls": {
        "show_filters": true,
        "show_visualizations": true,
        "show_table": true,
        "show_cards": true
      },
      "table": {
        "columns": [
          {"key": "peptide", "label": "Peptide", "format": "text"},
          {"key": "allele", "label": "Allele", "format": "text"},
          {"key": "priority_score_maximum", "label": "Max Priority Score", "format": "float"},
          {"key": "mhcflurry_2.1.1.aff", "label": "MHCFlurry Aff", "format": "float"},
          {"key": "ccf", "label": "CCF", "format": "float"},
          {"key": "vaf", "label": "VAF", "format": "float"},
          {"key": "tpm", "label": "Log2(TPM)", "format": "log2"},
          {"key": "antigen_source", "label": "Source", "format": "text"}
        ]
      }
    },
    {
      "id": "qc",
      "label": "QC",
      "renderer": "qc_summary",
      "source": "qc"
    }
  ]
}

Generic table example:

{
  "schema_version": "1.0",
  "name": "Somatic variation report",
  "description": "Somatic variant calls and run-level QC.",
  "bundle_format": "raft-report-bundle-v1",
  "sections": [
    {
      "id": "somatic_variants",
      "label": "Somatic variants",
      "renderer": "table",
      "default": true,
      "patterns": ["*somatic*.tsv"],
      "table": {
        "columns": [
          {"key": "chrom", "label": "Chrom", "format": "text"},
          {"key": "pos", "label": "Position", "format": "int"},
          {"key": "gene", "label": "Gene", "format": "text"},
          {"key": "effect", "label": "Effect", "format": "text"},
          {"key": "vaf", "label": "VAF", "format": "float"}
        ]
      }
    },
    {
      "id": "qc",
      "label": "QC",
      "renderer": "qc_summary",
      "source": "qc"
    }
  ]
}

QC-only example:

{
  "schema_version": "1.0",
  "name": "HLA typing QC",
  "description": "Review HLA typing outputs and quality-control metrics.",
  "bundle_format": "raft-report-bundle-v1",
  "sections": [
    {
      "id": "qc",
      "label": "QC",
      "renderer": "qc_summary",
      "source": "qc",
      "default": true
    },
    {
      "id": "files",
      "label": "Files",
      "renderer": "file_index",
      "patterns": ["*"]
    }
  ]
}

Report template fields

bundle_format: Identifies the report bundle format the viewer expects. Current RAFT bundles use raft-report-bundle-v1.
layout: Declares standard viewer layout expectations. The current viewer always uses patient navigation on the left, supports patient groups, and lets users collapse the sidebar.
sections: Defines patient-level tabs. Each section should define a stable id and display label.
renderer: Selects how a section is displayed. Supported values are table for generic TSV/TXT tables, qc_summary for built-in QC summaries, file_index for a list of bundle files, and lens_antigen_report for the LENS-specific pMHC report.
patterns: Optional file globs used by table and file_index sections. For example, ["*somatic*.tsv"] restricts a table section to matching bundle files. If omitted, all loaded TSV/TXT report files are eligible.
controls: Optional controls for lens_antigen_report sections. Set show_filters, show_visualizations, show_table, or show_cards to false to hide that part of the LENS report section.
table.columns: Optional table column list for table and lens_antigen_report sections. Each column needs key and label. If omitted for a generic table section, RAFT infers columns from the first loaded row. Supported format values are text, string, float, and log2.

Note

The report viewer is section-driven. Use lens_antigen_report only when the workflow emits LENS-style pMHC rows. Other workflows should usually start with table, qc_summary, and file_index sections.

Testing templates

To test workflow-owned templates locally:

Add the template files to the workflow configuration repository.
Run raft run or raft run-demo for the workflow and version that should use the templates.
Open the manifest generator or report viewer through RAFT.
Confirm that workflow labels, sample types, requirements, and report bundle behavior match the template.

For hosted UI testing, make sure the template files are committed to the public workflow configuration repository. The hosted manifest generator can fetch manifest-ui.json directly from GitLab when the local RAFT API is not available.