Working with Outputs#

This guide covers how to register processing results back into B-Fabric using bfabric-app-runner.

Overview#

After an app finishes processing, its output files and datasets need to be registered in B-Fabric. The output system supports three types of output specifications, defined in an outputs.yml file.

Output YAML Format#

- type: bfabric_copy_resource
  local_path: results/output.raw
  store_entry_path: output.raw

- type: bfabric_dataset
  local_path: results/summary.csv
  separator: ","
  name: "Results Summary"

- type: bfabric_link
  name: "Analysis Report"
  url: "https://example.com/report/123"

Output Spec Types#

bfabric_copy_resource#

Copies a local file to the B-Fabric storage and registers it as a resource.

- type: bfabric_copy_resource
  local_path: results/output.mzML
  store_entry_path: output.mzML
  store_folder_path: /path/in/store
  update_existing: NO
  protocol: scp

local_path (str, required): Path to the local file (relative to the chunk directory).
store_entry_path (str, optional): Filename in the B-Fabric storage.
store_folder_path (str, optional): Directory path within the storage.
update_existing (str, optional): How to handle existing resources. See UpdateExisting below.
protocol (str, optional): Transfer protocol. Currently "scp".

bfabric_dataset#

Registers a local tabular file as a B-Fabric dataset.

- type: bfabric_dataset
  local_path: results/summary.csv
  separator: ","
  name: "Experiment Results"
  has_header: true
  invalid_characters: remove

local_path (str, required): Path to the local CSV/TSV file.
separator (str, optional): Column separator character.
name (str, optional): Display name for the dataset in B-Fabric.
has_header (bool, optional): Whether the file has a header row.
invalid_characters (str, optional): How to handle invalid characters.

bfabric_link#

Creates a link resource in B-Fabric pointing to an external URL.

- type: bfabric_link
  name: "Interactive Report"
  url: "https://example.com/report/456"
  update_existing: IF_EXISTS

name (str, required): Display name for the link.
url (str, required): The URL to link to.
entity_type (str, optional): B-Fabric entity type to associate the link with.
entity_id (int, optional): B-Fabric entity ID to associate the link with.
update_existing (str, optional): How to handle existing links. See UpdateExisting below.

UpdateExisting Behavior#

The update_existing field controls what happens when a resource or link with the same identity already exists in B-Fabric:

NO: Do not update. Create a new resource (default behavior).
IF_EXISTS: Update the existing resource if one is found; otherwise create a new one.
REQUIRED: The resource must already exist. Raises an error if not found.

CLI Commands#

Register all outputs#

bfabric-app-runner outputs register outputs.yml workunit_ref

outputs_yaml: Path to the outputs YAML file.
workunit_ref: The workunit reference (ID or URI).
--ssh-user: SSH user for remote file transfers.
--force-storage: Override the storage location.

Register a single file#

bfabric-app-runner outputs register-single-file results/output.mzML \
  --workunit-ref 12345 \
  --store-entry-path output.mzML

local_path: Path to the local file.
--workunit-ref (required): The workunit reference.
--store-entry-path: Filename in the B-Fabric storage.
--store-folder-path: Directory path within the storage.
--update-existing: UpdateExisting behavior (NO, IF_EXISTS, or REQUIRED).
--ssh-user: SSH user for remote transfers.
--force-storage: Override the storage location.

Validating Output Specs#

Validate an outputs YAML file:

bfabric-app-runner validate outputs-spec outputs.yml

Working with Outputs

Contents