♟️Syntax for the pipeline-forms.yml file
How to create valid and meaningful forms for your pipelines
Extend the built-in Pipeline feature with PFO fields in 3 steps:
Create fields
Add fields to forms
Connect forms with pipelines
4. (Optional) - Group fields into presets - prefill fields and create variations
5. (Optional) - Validate form before a commit - with the online validator
Creating fields
This is a basic example for creating a text and a select field with some options.
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:
label*
display name for the field
Will be visible on the form.
type*
expected field type
Will determine field type and options.
name*
The value can be referred from the configuration as an ID.
note
description for the fields
Will be visible under the field as a helper text.
defaultValue
predefined value
The value will be added by default on the form.
mandatory
true value makes the field required
The field can not be empty when submitting.
availableValues**
can be added at fields with a fix set of values
When values can be selected from a strict list.
secure
true value makes the field hidden
Password and other secret values that should not be shared (even viewed) after inserting.
hidden
true value makes the field not showing on the form
Make a field prefilled in the background, without the possibility to change the value. Like a hard coded variable.
readonly
true value makes the field visible on the form, but default value can not be overwritten
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.
regex
a regular expression pattern to validate the input value
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.
* = 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
:
Select
secure
mandatory
note
readonly
defaultValue
availableValues
- &select-example
label: Select field
type: select
name: TEST_SELECT_FIELD
defaultValue: One
availableValues:
- One
- Two
- Three
Remote Select*
with Variables
secure
mandatory
note
readonly
availableValues
url
path
headers
(optional)method
(optional, default: GET)body
(optional)
- &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&page_size=100&name=8"
path: "$.results.[*].name"
headers:
- X-Header-1: value1
- X-Header-2: value2
method: POST
body: "{'limit': 10}"
Text
secure
mandatory
note
readonly
defaultValue
regex
hidden
- &text-example
label: Text field
type: text
name: TEST_TEXT_FIELD
defaultValue: I am a test
regex: .*
Textarea
secure
mandatory
note
readonly
defaultValue
regex
hidden
- &textarea-example
label: Text Area
name: TEXT_AREA_FIELD
type: textarea
defaultValue: |
Line1
Line2
regex: .*
Number
secure
mandatory
note
readonly
defaultValue
regex
- &number-example
label: Number
type: number
name: number
defaultValue: 24
regex: .*
Checkbox (single select)
secure
mandatory
note
readonly
defaultValue
true | false
- &checkbox-example
label: Checkbox field
type: checkbox
name: TEST_CHECKBOX_FIELD
defaultValue: true
Checkbox group (multi-select)
secure
mandatory
note
readonly
availableValues
- &checkbox-group-example
label: Checkbox group
type: checkbox_group
name: TEST_CHECKBOX_GROUP
availableValues:
- First
- Second
- Third
Radio button
secure
mandatory
note
readonly
defaultValue
availableValues
- &radio-field-example
label: Radio field
type: radio
name: TEST_RADIO_FIELD
mandatory: true
defaultValue: One
availableValues:
- One
- Two
- Three
Date
secure
mandatory
note
readonly
defaultValue
Format: yyyy-mm-dd
- &date-example
label: Date field
type: date
name: TEST_DATE_FIELD
defaultValue: 2023-05-06
When adding a field right at the forms you don't need to use the anchor.
*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.
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.
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. This way you can reference an existing object and override only some of its properties.
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
Last updated