# JSON-Based input forms

### Introduction

Pipelines defined using the "Code" mode require an XML or JSON-based input form to define the fields shown on the launch view in the user interface (UI).

To create a JSON-based Nextflow (or CWL) pipeline, go to **Projects > your\_project > Flow > Pipelines > +Create > Nextflow (or CWL) > JSON-based**.

Three files, located on the inputform files tab, work together for evaluating and presenting JSON-based input.

* **inputForm.json** contains the actual input form which is rendered when starting the pipeline run.
* **onRender.js** is triggered when a value is changed.
* **onSubmit.js** is triggered when starting a pipeline via the GUI or API.

Use **+ Create** to add additional files and **Simulate** to test your inputForms.

Scripting execution supports crossfield validation of the values, hiding fields, making them required, .... based on value changes.

***

### inputForm.json

The JSON schema allowing you to define the input parameters. See the [inputForm.json](https://help.ica.illumina.com/project/p-flow/f-pipelines/json-based-input-forms/inputform.json-syntax) page for syntax details.

{% hint style="info" %}
The inputForm.json file has a size limit of 10 MB and a maximum of 200 fields.
{% endhint %}

## Parameter types <a href="#pipelineinputforms-parametertypes" id="pipelineinputforms-parametertypes"></a>

<table><thead><tr><th width="181">Type</th><th>Usage</th></tr></thead><tbody><tr><td>textbox</td><td>Corresponds to stringType in xml.</td></tr><tr><td>checkbox</td><td>A checkbox that supports the option of being required, so can serve as an active consent feature. (corresponds to the booleanType in xml).</td></tr><tr><td>radio</td><td>A radio button group to select one from a list of choices. The values to choose from must be unique.</td></tr><tr><td>select</td><td>A dropdown selection to select one from a list of choices. This can be used for both single-level lists and tree-based lists.</td></tr><tr><td>number</td><td>The value is of Number type in javascript and Double type in java. (corresponds to doubleType in xml).</td></tr><tr><td>integer</td><td>Corresponds to java Integer.</td></tr><tr><td>data</td><td>Data such as files.</td></tr><tr><td>section</td><td>For splitting up fields, to give structure. Rendered as subtitles. No values are to be assigned to these fields.</td></tr><tr><td>text</td><td>To display informational messages. No values are to be assigned to these fields.</td></tr><tr><td>fieldgroup</td><td>Can contain parameters or other groups. Allows to have repeating sets of parameters, for instance when a father|mother|child choice needs to be linked to each file input. So if you want to have the same elements multiple times in your form, combine them into a fieldgroup.<br>Does not support the emptyValuesAllowed attribute.</td></tr></tbody></table>

## Parameter Attributes <a href="#pipelineinputforms-parameterattributes" id="pipelineinputforms-parameterattributes"></a>

These attributes can be used to configure all parameter types.

<table><thead><tr><th width="251">Attribute</th><th>Purpose</th></tr></thead><tbody><tr><td>label</td><td>The display label for this parameter. Optional but recommended, id will be used if missing.</td></tr><tr><td>minValues</td><td>The minimal amount of values that needs to be present. Default when not set is 0. Set to >=1 to make the field required.</td></tr><tr><td>maxValues</td><td>The maximal amount of values that need to be present. Default when not set is 1.</td></tr><tr><td>minMaxValuesMessage</td><td>The error message displayed when minValues or maxValues is not adhered to. When not set, a default message is generated.</td></tr><tr><td>helpText</td><td>A helper text about the parameter. Will be displayed in smaller font with the parameter.</td></tr><tr><td>placeHolderText</td><td>An optional short hint ( a word or short phrase) to aid the user when the field has no value.</td></tr><tr><td>value</td><td>The value of the parameter. Can be considered default value.</td></tr><tr><td>minLength</td><td>Only applied on type="textbox". Value is a positive integer.</td></tr><tr><td>maxLength</td><td>Only applied on type="textbox". Value is a positive integer.</td></tr><tr><td>min</td><td><p>Minimal allowed value for '<strong>integer</strong>' and '<strong>number</strong>' type.</p><ul><li>for 'integer' type fields the minimal and maximal values are -100000000000000000 and 100000000000000000.</li><li>for 'number' type fields the max precision is 15 significant digits and the exponent needs to be between -300 and +300.</li></ul></td></tr><tr><td>max</td><td><p>Maximal allowed value for '<strong>integer</strong>' and '<strong>number</strong>' type.</p><ul><li>for 'integer' type fields the minimal and maximal values are -100000000000000000 and 100000000000000000.</li><li>for 'number' type fields the max precision is 15 significant digits and the exponent needs to be between -300 and +300.</li></ul></td></tr><tr><td>choices</td><td>A list of choices with for each a "value", "text" (is label), "selected" (only 1 true supported), "disabled". "parent" can be used to build hierarchical choicetrees. "availableWhen" can be used for conditional presence of the choice based on values of other fields. Parent and value must be unique, you can not use the same value for both.</td></tr><tr><td>fields</td><td>The list of sub fields for type fieldgroup.</td></tr><tr><td>dataFilter</td><td>For defining the filtering when type is 'data'. Use <strong>nameFilter</strong> for matching the name of the file, <strong>dataFormat</strong> for file format and <strong>dataType</strong> for selecting between files and directories. Tip: <em>To see the data formats, open the file details in ICA and look at the Format on the data details. You can expand the dropdown list to see the syntax.</em></td></tr><tr><td>regex</td><td>The regex pattern the value must adhere to. Only applied on type="textbox".</td></tr><tr><td>regexErrorMessage</td><td>The optional error message when the value does not adhere to the "regex". A default message will be used if this parameter is not present. It is highly recommended to set this as the default message will show the regex which is typically very technical.</td></tr><tr><td>hidden</td><td>Makes this parameter hidden. Can be made visible later in onRender.js or can be used to set hardcoded values of which the user should be aware.</td></tr><tr><td>disabled</td><td>Shows the parameter but makes editing it impossible. The value can still be altered by onRender.js.</td></tr><tr><td>emptyValuesAllowed</td><td>When maxValues is 1 or not set and emptyValuesAllowed is true, the values may contain null entries. Default is false.</td></tr><tr><td>updateRenderOnChange</td><td>When true, the onRender javascript function is triggered each time the user changes the value of this field. Default is false.</td></tr><tr><td>dropValueWhenDisabled</td><td>When this is present and true and the field has <em>disabled</em> being true, then the value will be omitted during the submit handling (on the onSubmit result).</td></tr></tbody></table>

<details>

<summary>Tree structure example</summary>

"choices" can be used for a single list or for a tree-structured list. See below for an example for how to set up a tree structure.

```json
{
  "fields": [
    {
      "id": "myTreeList",
      "type": "select",
      "label": "Selection Tree Example",
      "choices": [
        {
          "text": "trunk",
          "value": "treetrunk"
        },
        {
          "text": "branch",
          "value": "treebranch",
          "parent":"treetrunk"
        },
        {
          "text": "leaf",
          "value": "treeleaf",
          "parent":"treebranch"
        },
        {
          "text": "bird",
          "value": "happybird",
          "parent":"treebranch"
        },
        {
          "text": "cat",
          "value": "cat",
          "parent": "treetrunk",
          "disabled": true
        }
      ],
      "minValues": 1,
      "maxValues": 3,
      "helpText": "This is a tree example"
    }
  ]
}
```

</details>

## Experimental Features

<table><thead><tr><th width="267">Feature</th><th></th></tr></thead><tbody><tr><td>Streamable inputs</td><td>Adding <code>"streamable":true</code> to an input field of type "<strong>data</strong>" makes it a streamable input.</td></tr></tbody></table>

***

### onSubmit.js

The onSubmit.js javascript function receives an input object which holds information about the chosen values of the input form and the pipeline and pipeline execution request parameters. This javascript function is not only triggered when submitting a new pipeline execution request in the user interface, but also when submitting one through the rest API..

#### Input parameters

<table><thead><tr><th width="210">Value</th><th>Meaning</th></tr></thead><tbody><tr><td>settings</td><td>The value of the setting fields. Corresponds to <code>settingValues</code> in the onRender.js. This is a map with field id as key and an array of field values as value. For convenience, values of single-value fields are present as the individual value and not as an array of length 1. In case of fieldGroups, the value can be multiple levels of arrays. For fields of type <em>data</em> the values in the json are data ids (fil.xxxx). To help with validation, these are expanded and made available as an object here containing the <em>id</em>, <em>name</em>, <em>path</em>, <em>format</em>, <em>size</em> and a boolean indicating whether the data is <em>external</em>. This info can be used to validate or pick the chosen storageSize.</td></tr><tr><td>settingValues</td><td>To maximize the opportunity for reusing code between onRender and onSubmit, the 'settings' are also exposed as <code>settingValues</code> like in the onRender input.</td></tr><tr><td>pipeline</td><td>Info about the pipeline: code, tenant, and description are all available in the pipeline object as string.</td></tr><tr><td>analysis</td><td>Info about this run: userReference, userName, and userTenant are all available in the analysis object as string.</td></tr><tr><td>storageSize</td><td>The storage size as chosen by the user. This will initially be null. StorageSize is an object containing an 'id' and 'name' property.</td></tr><tr><td>storageSizeOptions</td><td>The list of storage sizes available to the user when creating an analysis. Is a list of StorageSize objects containing an 'id' and 'name' property.</td></tr><tr><td>analysisSettings</td><td>The input form json as saved in the pipeline. So the original json, without eventual changes.</td></tr><tr><td>currentAnalysisSettings</td><td>The current input form JSON as rendered to the user. This can contain already applied changes form earlier onRender passes. Null in the first call, when context is 'Initial' or when analysis is created through CLI/API.</td></tr></tbody></table>

#### Return values (taken from the response object)

<table><thead><tr><th width="191">Value</th><th>Meaning</th></tr></thead><tbody><tr><td>settings</td><td>The value of the setting fields. This allows modifying the values or applying defaults and such. Or taking info of the pipeline or analysis input object. When settings are not present in the onSubmit return value object, they are assumed to be not modified.</td></tr><tr><td>validationErrors</td><td>A list of AnalysisError essages representing validation errors. <strong>Submitting a pipeline execution request is not possible while there are still validation errors.</strong></td></tr><tr><td>analysisSettings</td><td>The input form json with potential applied changes. The discovered changes will be applied in the UI when viewing the analysis.</td></tr></tbody></table>

#### AnalysisError

This is the object used for representing validation errors.

<table><thead><tr><th width="204">Value</th><th>Meaning</th></tr></thead><tbody><tr><td>fieldId / FieldId</td><td>The field which has an erroneous value. When not present, a general error/warning is displayed. To display an error on the storage size, use the <code>storageSize</code>Fieldid.</td></tr><tr><td>index / Index</td><td>The 0-starting index of the value which is incorrect. Use this when a particular value of a multivalue field is not correct. When not present, the entire field is marked as erroneous. The value can also be an array of indexes for use with fieldgroups. For instance, when the 3rd field of the 2nd instance of a fieldgroup is erroneous, a value of [ 1 , 2 ] is used.</td></tr><tr><td>message / Message</td><td>The error/warning message to display.</td></tr></tbody></table>

***

### onRender.js

Receives an input object which contains information about the current state of the input form, the chosen values and the field value change that triggered the onrender call. It also contains pipeline information. Changed objects are present in the onRender return value object. Any object not present is considered to be unmodified. Changing the storage size in the start analysis screen triggers an onRender execution with storageSize as changed field.

#### Input Parameters

<table><thead><tr><th width="235"></th><th></th></tr></thead><tbody><tr><td>context</td><td><p>"Initial"/"FieldChanged"/"Edited".</p><ul><li><strong>Initial</strong> is the value when first displaying the form when a user opens the <em>start run</em> screen.</li><li>The value is <strong>FieldChanged</strong> when a field with <code>'updateRenderOnChange'=true</code> is changed by the user.</li><li><strong>Edited</strong> (Not yet supported in ICA) is used when a form is displayed later again, this is intended for draft runs or when editing the form during reruns.</li></ul></td></tr><tr><td>changedFieldId</td><td>The id of the field that changed and which triggered this onRender call. context will be <code>FieldChanged</code>. When the storage size is changed, the fieldId will be <code>storageSize</code>.</td></tr><tr><td>analysisSettings</td><td>The input form json as saved in the pipeline. This is the original json, without changes.</td></tr><tr><td>currentAnalysisSettings</td><td>The current input form json as rendered to the user. This can contain already applied changes form earlier onRender passes. Null in the first call, when context is <code>Initial</code>.</td></tr><tr><td>settingValues</td><td>The current value of all settings fields. This is a map with field id as key and an array of field values as value for multivalue fields. For convenience, values of single-value fields are present as the individual value and not as an array of length 1. In case of fieldGroups, the value can be multiple levels of arrays. For fields of type <em>data</em> the values in the json are data ids (fil.xxxx). To help with validation, these are expanded and made available as an object here containing the <em>id</em>, <em>name</em>, <em>path</em>, <em>format</em>, <em>size</em> and a boolean indicating whether the data is <em>external</em>. This info can be used to validate or pick the chosen storageSize.</td></tr><tr><td>pipeline</td><td>Information about the pipeline: code, tenant and description are all available in the pipeline object as string.</td></tr><tr><td>analysis</td><td>Information about this run: userReference, userName, and userTenant are all available in the analysis object as string.</td></tr><tr><td>storageSize</td><td>The storage size as chosen by the user. This will initially be null. StorageSize is an object containing an 'id' and 'name' property.</td></tr><tr><td>storageSizeOptions</td><td>The list of storage sizes available to the user when creating an analysis. Is a list of StorageSize objects containing an 'id' and 'name' property.</td></tr></tbody></table>

#### Return values (taken from the response object)

<table><thead><tr><th width="191">Value</th><th>Meaning</th></tr></thead><tbody><tr><td>analysisSettings</td><td>The input form json with potential applied changes. The discovered changes will be applied in the UI.</td></tr><tr><td>settingValues</td><td>The current, potentially altered map of all setting values. These will be updated in the UI.</td></tr><tr><td>validationErrors</td><td>A list of RenderMessages representing validation errors. <strong>Submitting a pipeline execution request is not possible while there are still validation errors.</strong></td></tr><tr><td>validationWarnings</td><td>A list of RenderMessages representing validation warnings. <strong>A user may choose to ignore these validation warnings and start the pipeline execution request.</strong></td></tr><tr><td>storageSize</td><td><p>The suitable value for storageSize. Must be one of the options of input.storageSizeOptions. When absent or null, it is ignored.</p><p>validation errors and validation warnings can use 'storageSize' as fieldId to let an error appear on the storage size field. 'storageSize' is the value of the changedFieldId when the user alters the chosen storage size.</p></td></tr></tbody></table>

#### RenderMessage

This is the object used for **representing validation errors and warnings**. The attributes can be used with first letter lowercase (consistent with the input object attributes) or uppercase.

<table><thead><tr><th width="204">Value</th><th>Meaning</th></tr></thead><tbody><tr><td>fieldId / FieldId</td><td>The field which has an erroneous value. When not present, a general error/warning is displayed. To display an error on the storage size, use the <code>storageSize</code>Fieldid.</td></tr><tr><td>index / Index</td><td>The 0-starting index of the value which is incorrect. Use this when a particular value of a multivalue field is not correct. When not present, the entire field is marked as erroneous. The value can also be an array of indexes for use with fieldgroups. For instance, when the 3rd field of the 2nd instance of a fieldgroup is erroneous, a value of [ 1 , 2 ] is used.</td></tr><tr><td>message / Message</td><td>The error/warning message to display.</td></tr></tbody></table>