# Syntax for the pipeline-forms.yml file

Extend the built-in Pipeline feature with PFO fields in 3 steps:

1. Create fields
2. Add fields to forms
3. Connect forms with pipelines

{% hint style="success" %}
**4. (Optional)** - Group fields into presets - prefill fields and create variations

**5. (Optional)** - Validate form before a commit - with the online validator
{% endhint %}

## Creating fields

{% hint style="info" %}
Fields and forms can be added by editing the `pipeline-forms.yml,`which is a custom file you have to create in addition to having the`bitbucket-pipelines.yml`.
{% endhint %}

This is a basic example for creating a text and a select field with some options. 

```yaml
fields:
  - &example-text-field
    label: Text field
    type: text
    name: TEST_TEXT_FIELD
    defaultValue: I am a test
  - &mandatory-text-field
    <<: *example-text-field
    mandatory: true
  - &example-select-field
    label: Select field
    type: select
    name: TEST_SELECT_FIELD
    note: "Select any value from below list"
    defaultValue: One
    availableValues:
      - One
      - Two
      - Three
```

You can also use the characters '<<:' to add more values to previously defined fields.

### Available attributes

Keys and values can be selected from the following set:

<table data-full-width="true"><thead><tr><th width="228">Key</th><th>Value</th><th>Usage</th></tr></thead><tbody><tr><td>label*</td><td>display name for the field</td><td>Will be visible on the form.</td></tr><tr><td>type*</td><td>expected field type</td><td>Will determine field type and options.</td></tr><tr><td>name*</td><td></td><td>The value can be referred from the configuration as an ID.</td></tr><tr><td>note</td><td>description for the fields</td><td>Will be visible under the field as a helper text.</td></tr><tr><td>defaultValue</td><td>predefined value</td><td>The value will be added by default on the form.</td></tr><tr><td>mandatory</td><td><strong>true</strong> value makes the field required</td><td>The field can not be empty when submitting.</td></tr><tr><td>availableValues**</td><td>can be added at fields with a fix set of values</td><td>When values can be selected from a strict list.</td></tr><tr><td>secure</td><td><strong>true</strong> value makes the field hidden</td><td>Password and other secret values that should not be shared (even viewed) after inserting.</td></tr><tr><td>hidden</td><td><strong>true</strong> value makes the field not showing on the form</td><td>Make a field prefilled in the background, without the possibility to change the value. Like a hard coded variable.</td></tr><tr><td>readonly</td><td><strong>true</strong> value makes the field visible on the form, but default value can not be overwritten</td><td>Make a field prefilled, but show on the form to let the user know. This is useful while using presets, to fill and protect several fields in advance.</td></tr><tr><td>regex</td><td>a regular expression pattern to validate the input value</td><td>Use this property to enforce a specific format or pattern for user input. The input value must match the provided regular expression for successful validation.</td></tr></tbody></table>

*\* = required*

*\*\*= required where aplicable*

### Available field types

In PFO you can extend your pipelines with the following field types while editing the `pipeline-forms.yml`:

<table data-full-width="true"><thead><tr><th>Field Type</th><th>Available modifiers</th><th>Example snippet</th></tr></thead><tbody><tr><td><strong>Select</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><code>defaultValue</code></li><li><code>availableValues</code></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- &#x26;select-example
  label: Select field
  type: select
  name: TEST_SELECT_FIELD
  defaultValue: One
  availableValues:
    - One
    - Two
    - Three
</code></pre></td></tr><tr><td><p><strong>Remote Select*</strong> </p><p><strong>with</strong> <a data-mention href="variables">variables</a><br></p></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><p><code>availableValues</code></p><ul><li><code>url</code></li><li><code>path</code></li><li><code>headers</code> (optional)</li><li><code>method</code> (optional, default: GET)</li><li><code>body</code> (optional)</li></ul></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- &#x26;remote-select-example
  label: Remote select field
  type: remote_select
  name: TEST_REMOTE_SELECT_FIELD
  availableValues:
    url: "https://hub.docker.com/v2/repositories/atlassian/jira-software/tags/?page=1&#x26;page_size=100&#x26;name=8"
    path: "$.results.[*].name"
    headers:
        - X-Header-1: value1
        - X-Header-2: value2
    method: POST
    body: "{'limit': 10}"
</code></pre></td></tr><tr><td><strong>Text</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><code>defaultValue</code></li><li><code>regex</code></li><li><code>hidden</code></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml"> - &#x26;text-example
   label: Text field
   type: text
   name: TEST_TEXT_FIELD
   defaultValue: I am a test
   regex: .*

</code></pre></td></tr><tr><td><strong>Textarea</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><code>defaultValue</code></li><li><code>regex</code></li><li><code>hidden</code></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- \&textarea-example
label: Text Area
name: TEXT\_AREA\_FIELD
type: textarea
defaultValue: |
Line1
Line2
regex: .\* </code></pre></td></tr><tr><td><strong>Number</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><code>defaultValue</code></li><li><code>regex</code></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- \&number-example
label: Number
type: number
name: number
defaultValue: 24
regex: .\* </code></pre></td></tr><tr><td><strong>Checkbox (single select)</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><p><code>defaultValue</code></p><ul><li>true | false</li></ul></li></ul></td><td><pre class="language-yaml" data-full-width="true"><code class="lang-yaml">- \&checkbox-example
label: Checkbox field
type: checkbox
name: TEST\_CHECKBOX\_FIELD
defaultValue: true </code></pre></td></tr><tr><td><strong>Checkbox group (multi-select)</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><code>availableValues</code></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- \&checkbox-group-example\
label: Checkbox group
type: checkbox\_group
name: TEST\_CHECKBOX\_GROUP
availableValues:
\- First
\- Second
\- Third </code></pre></td></tr><tr><td><strong>Radio button</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><code>defaultValue</code></li><li><code>availableValues</code></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- \&radio-field-example
label: Radio field
type: radio
name: TEST\_RADIO\_FIELD
mandatory: true
defaultValue: One
availableValues:
\- One
\- Two
\- Three </code></pre></td></tr><tr><td><strong>Date</strong></td><td><ul><li><code>secure</code></li><li><code>mandatory</code></li><li><code>note</code></li><li><code>readonly</code></li><li><p><code>defaultValue</code></p><ul><li><code>Format: yyyy-mm-dd</code></li></ul></li></ul></td><td><pre class="language-yaml"><code class="lang-yaml">- \&date-example
label: Date field
type: date
name: TEST\_DATE\_FIELD
defaultValue: 2023-05-06 </code></pre></td></tr></tbody></table>

When adding a field right at the forms you don't need to use the anchor.

{% hint style="warning" %}
\*When using remote select, the specified URL must point to a publicly accessible endpoint which must give a JSON formatted response body. The path must be specified as a JSON Path, which you can experiment with using the <https://jsonpath.com/> tool.&#x20;
{% endhint %}

## Building forms

Fields need to be added to the `pipeline-forms.yml` first, then they can be added to forms. Forms will be rendered on the UI when selected.

```yaml
fields:
  - &example-text-field
    label: Text field
    type: text
    name: EXAMPLE_TEXT_FIELD
    defaultValue: I am a test
    mandatory: true
    regex: .*
  - &example-select-field
    label: Select field
    type: select
    name: EXAMPLE_SELECT_FIELD
    note: "Select any value from below list"
    defaultValue: Select 1
    availableValues:
      - Select 1
      - Select 2
      - Select 3
  - &example-radio-field
    label: Radio field
    type: radio
    name: EXAMPLE_RADIO_FIELD
    availableValues:
      - Radio 1
      - Radio 2
forms:
  - name: Small form with radio
    fields:
      - *example-text-field
      - *example-radio-field
    pipeline: test
    groups:
      - TEST_GROUP
      - JIRA
  - name: Small form with select
    fields:
      - *example-text-field
      - *example-select-field
    groups:
      - JIRA
    pipeline: test
  - name: Big form without group
    fields:
      - *example-text-field
      - *example-radio-field
      - *example-select-field
    pipeline: test2
```

## Presets (Groups)

If you want a field or form similar to an existing one but with different default values you don't have to copy the whole object, just use the power of [YAML Anchors](https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/). This way you can reference an existing object and override only some of its properties.&#x20;

```yaml
fields:
  - &example-text-field
    label: Text field
    type: text
    name: EXAMPLE_TEXT_FIELD
    defaultValue: I am a test
    mandatory: true
    regex: .*
  - &example-select-field
    label: Select field
    type: select
    name: EXAMPLE_SELECT_FIELD
    note: "Select any value from below list"
    defaultValue: Select 1
    availableValues:
      - Select 1
      - Select 2
      - Select 3
  - &example-radio-field
    label: Radio field
    type: radio
    name: EXAMPLE_RADIO_FIELD
    availableValues:
      - Radio 1
      - Radio 2
forms:
  - name: Small form with radio
    fields:
      - *example-text-field
      - *example-radio-field
    pipeline: test
    groups:
      - TEST_GROUP
      - JIRA
  - name: Small form with select
    fields:
      - *example-text-field
      - *example-select-field
    groups:
      - JIRA
    pipeline: test
  - name: Big form without group
    fields:
      - *example-text-field
      - <<: *example-text-field
        defaultValues: Text field value
        readonly: true
      - *example-radio-field
      - *example-select-field
    pipeline: test2
```