Registering a method in the workbench

A method becomes visible in the workbench through one JSON file, its parameter definition, and one menu link. The definition gives the form its title, description and fields; the link opens that form. On submit the form's values become the job's params.json, so the definition also decides exactly what the method's scripts receive. This page describes the file, the field types, how the form is built and sent, and the one rule that matters most: the scripts must read every field you offer. Building the method itself is covered in Building a method from the template.

How the definition becomes a form

Every .json file in bf-workbench/src/models/analysis/ is read when a recordset or search page is rendered and handed to the page. A sidebar link carrying data-analysis="<title>" opens the Analysis form, which shows title as its heading, description beneath it, and builds one control per field. On submit the page collects the values, adds title, recordset_title and recordset_descr together with the set token and the record selection, and posts to the workbench, which counts the selected records and submits the job to the analysis service (see Running an analysis). When the scheduler packages the job, the values are written to params.json unchanged.

The definition file

{
  "title": "sequence-composition",
  "description": "Calculates nucleotide frequencies ...",
  "fields": [
    { "properties": { "type": "divider", "label": "Configuration" } },
    { "name": "marker",
      "properties": { "type": "select", "label": "Marker", "options": "markers", "default": [] } },
    { "name": "filter_seqlength_bp",
      "properties": { "type": "sliderminmax", "min_name": "filter_min_seqlength_bp",
                      "max_name": "filter_max_seqlength_bp", "label": "Sequence Length Filter",
                      "min": 0, "max": 4000, "step": 25, "density": 3.125,
                      "min_value": [100, 500], "max_value": [600, 4000], "default": [400, 1000] },
      "help": "Set the filter above 50% of the marker's length" }
  ]
}

title must equal the method's directory name in bf-analysis-jobs; it is also what users see as the form heading and in the Analysis panel. fields is an ordered list of four kinds of entry:

Entry	Shape	Renders as
Divider	{"properties": {"type": "divider", "label": ...}}	A section heading with a rule
Grid	{"grid": true, "fields": [...]}	Fields side by side; each field's col is its width out of 12, label above the control
Group	{"group": "Label", "fields": [...]}	One label on the left, several controls on the right
Field	{"name": ..., "properties": {...}, "help": ...}	One labelled control, with help as small text under it

Field types

properties.type chooses the control. label is the field's caption, required adds an asterisk and browser-side validation, and icon (a Tabler icon name) decorates selects and text inputs.

Type	Properties	What the job receives
select	options, default (a list containing the selected value)	One string
selectmultiple	options, default (list), placeholder	A list of strings, empty if nothing chosen
radio	options, default (one value), inline	One string
checkbox	options, default (list)	A list of strings
checkboxbool, switch	text, default (true or false)	true or false
slider	min, max, step, density, min_value, max_value, default, postfix	The value as a string
sliderminmax	As slider, plus min_name and max_name; default, min_value and max_value are [low, high] pairs	Two keys, min_name and max_name, each a string
text, textarea, date, daterange, hidden	default (rows for textarea)	A string; daterange sends <name>-start and <name>-end; hidden sends its default without showing a control

options is either a list of {"value", "label"} objects or the name of a list the page supplies. markers gives the markers present in the recordset, most common first. The field lists used by the tree and export forms are specimen_fields, taxonomy_fields, collection_fields, sequence_fields, record_organization_fields, forensic_extension_fields, forensic_extension___advanced_fields, individualization_extension_fields and feature_rollup_fields.

For sliders, min and max set the track and density the tick spacing, while min_value and max_value are the limits a handle snaps back to; a user cannot submit a value outside them. A postfix is appended to the displayed and submitted value.

Field names beginning labels_ are treated specially in the report: they appear in a Labels row rather than the Parameters grid (see Anatomy of a result package).

The menu entry

The form opens only from a sidebar link, which is written by hand in bf-workbench/src/templates/layout/sidenav.jinja2. Methods that return a report go under Data Analysis; export jobs go under Data Download:

<a href="#" class="side-nav-link" data-bs-toggle="modal"
   data-analysis="<title>" data-bs-target="#analysis-modal">
    <span class="menu-text">Human-readable name</span>
</a>

The menu text is free; the form heading and the Analysis panel still show the internal title.

What the job receives

For the definition above, params.json looks like this:

{
  "marker": "COI-5P",
  "filter_min_seqlength_bp": "400",
  "filter_max_seqlength_bp": "1000",
  "filter_stopcodon_exclude": false,
  "title": "sequence-composition",
  "recordset_title": "Small mammal sequences",
  "recordset_descr": "..."
}

Every field name appears, whether or not the user touched it; a range slider appears as its two names. Numbers from sliders are strings, so scripts must convert them. The report prints this file as the Parameters section.

The job must read every parameter

Nothing ties the definition to the stage scripts. A field the scripts never read is accepted by the API, written to params.json, printed in the report as if it had been applied, and has no effect. That is how the options listed on Known limitations of the methods came to be. The reverse also holds: a key that 1.validate.sh requires but the form does not send fails every submission.

So, for each field you add, decide which stage reads it and where it is applied, read it there with jq -r '.<name>' "$PARAMS", and have 1.validate.sh check that it is present and within the allowed values. If a method genuinely does not support an option, leave it out of the form rather than accepting it.

Good to know

Good to know: The definition is read on every page render, so deploying the file is enough; the workbench does not need a restart. The sidebar link is part of the template and ships with the workbench.

Good to know: The analysis service accepts any title. If it matches no method directory, the job is packaged, taken by the worker, and fails at its time limit without a result. Check the spelling before deploying.

Related

• Building a method from the template
• Testing a method
• Running an analysis
• Known limitations of the methods