sanger/limber

<!--
# @markup markdown
# @title Pipelines yaml files
-->

# Exports yaml files

There are a number of `*.yml` files located in `config/exports` these
configure the exports via the {ExportsController}. Limber automatically
loads all `.yml` files within this directory into {Export}.
Filenames, and the grouping of pipelines within files, have no functional
relevance, and are intended for organizational reasons.

Loading of yaml files is handled by {ConfigLoader::ExportsLoader} which
loads all files, detects potential duplicates, and is loaded by {Export}.

## An example file

This is an example yaml file configuring a handful of exports, demonstrating key
features

```yaml
---
concentrations_ngul:
  csv: concentrations_ngul
  plate_includes: wells.qc_results
duplex_seq_pcr_xp_concentrations_for_custom_pooling:
  csv: duplex_seq_pcr_xp_concentrations_for_custom_pooling
  plate_includes: wells.qc_results
  ancestor_purpose: LDS AL Lib Dil
hamilton_aggregate_cherrypick:
  csv: hamilton_aggregate_cherrypick
  plate_includes: wells.transfer_requests_as_target.source_asset
  workflow: Cherry Pick
```

The rest of the document describes the structure of this file, and what each of the keys do.

## Top level

Each file is a `.yml` file located in `config/exports`, it contains the
configuration for one or more {Export exports}.

The top level structure consists of series of keys, uniquely identifying each
export. Keys need to be unique across _all_ exports, not just those within
the same file. Limber will detect duplicate keys, and will raise an exception
on boot.

The values in turn are used to describe each {Export}. The valid options are details in Export below.

### Export

Each export is identified by a unique key, that forms the exports id. This key
is used in a similar manner to a primary key of a database, and will let your
export be found with `Export.find(id)`. This id will also form part of the url
for the export, so should be something meaningful to an end user.

This id should be referenced in the {file:docs/pipelines_yaml_files.md#file_links file links}
section of a purpose config to generate the appropriate links.

@see Export for the Ruby objects generated by this configuration.

```yaml
unique_export:
  csv: unique_export
  plate_includes: wells.transfer_requests_as_target.source_asset
  workflow: Cherry Pick
  ancestor_purpose: LDS AL Lib Dil
```

The other keys are detailed below.

#### csv

**[required]**

Determines the template in `app/views/exports` that will be used to render the
export. If possible, try and use the same value for the template and the id.
It is also used as the fallback option for the filename if the filename is not set.

```yaml
csv: unique_export
```

This example will use the `unique_export.csv.erb` file in the
`app/views/exports` directory.

#### plate_includes

plate_includes indicates a [JSON API](https://jsonapi.org) include request
parameter to eager-load data while fetching a plate.

[More details](https://jsonapi.org/format/#fetching-includes)

```yaml
plate_includes: wells.transfer_requests_as_target.source_asset
```

Default: `wells`

#### workflow

A simple string that can be presented in the rendered template to distinguish
between otherwise identical processes. Some liquid handlers may use this
information to validate that the correct file has been uploaded.

Examples in `hamilton_cherrypick_dilutions`

```yaml
workflow: Cherry Pick
```

#### ancestor_purpose

If this is supplied, the {ExportsController} will identify the first ancestor
(earliest) of the current plate with this purpose, and will assign it to
the instance variable `@ancestor_plate`.

Example in `app/views/exports/duplex_seq_pcr_xp_concentrations_for_custom_pooling.csv.erb`

```yaml
ancestor_purpose: LDS AL Lib Dil
```

#### filename

A method of specifiying what data is included in the filename of the export.

```yaml
filename:
  # The name of the export file
  name: 'example-name'
  # Includes the page number at the end of the filename
  include_page: true
  # Includes the labware's human barcode in the file, there is no default, either append or prepend is needed to show the barcode
  labware_barcode:
    # (Optional) Includes the name of the labware in the file
    append: true
    # (Optional) Add the name to the end of the file
    prepend: false
  # Includes the parent labware's human barcode, either append or prepend is needed to show the barcode
  parent_labware_barcode:
    # (Optional) Includes the name of the labware in the file
    append: true
    # (Optional) Add the name to the end of the file
    prepend: true
```

#### file_extension

The file extension of the export file. Defaults to `csv`.

```yaml
file_extension: 'tsv'
```

### Testing

Test coverage for new exports can be found in `spec/views/exports` (covering
each view) with further coverage in `spec/controllers/exports_controller_spec.rb`