Changing Build Parameter Type and UI Appearance
When adding a build parameter, you can extend its definition with meta-information, or specification. The parameter's specification defines how its controls are presented and validated in the Run Custom Build dialog.
By adding a typed specification to a parameter, you make it a typed parameter. Typed parameters are more understandable for non-developers and make experience with builds more user-friendly.
Example: A build configuration has a parameter that defines if a build has to include a license or not. The parameter can be either true or false (default). For a regular user, it might not be clear which build parameter is responsible for the license generation and what its values mean. It is not a problem when builds run with the default configuration. However, if a user wants to run a custom build, the variety of available parameters might confuse them. Using the build parameter specification, you can make the parameters' appearance in the Run Custom Build dialog more readable.
Adding Parameter Specification
To add a specification to a build parameter, click Edit in the Spec section when editing/adding a build parameter.
All parameter specifications support the following common settings:
Setting | Description |
|---|---|
Label | An alternative text that can be displayed near the control in the Run Custom Build dialog. |
Description | A text that is displayed below the control. Might contain a more detailed explanation on how to use the control. |
Display | A display mode:
|
Read-only | If enabled, it will be impossible to override the parameter's default value. |
Type | A UI field type: |
Types of Parameters
Text Type
This is the default option which is a usual text string.
For this type, it is possible to define the allowed value:
Any
Not empty
Regex: specify a Java-style regular expression to validate the field value, as well as the message to show if the validation fails.
Checkbox Type
A true/false option represented by a checkbox.
For this type, it is possible to specify the values of the parameter that will be applied depending on the checkbox state (true or false).
We recommend that you keep the unchecked value equal to the default value and specify a custom checked value.
Depending on how the build is triggered, the checkbox behavior will be as follows:
If the build is triggered by an automatic trigger or by clicking Run (without the Run Custom Build dialog), the default value is used.
If the build is triggered via the Run Custom Build dialog without changing anything, the "unchecked" value is used, if it is not empty and differs from the default one. If empty, the default value is used.
If the build is triggered via the Run Custom Build dialog with the box checked, the "checked" value is used, if it is not empty. If it is empty, the
truevalue is used.
Select Type
A "select one" or "select many" control to set the value to one of the predefined settings.
To allow selection of multiple options, enable the Allow multiple option. In the Items field, specify a newline-separated list of items of the selector menu. Use the following syntax label => value to display a human-readable label to represent a value or just value to display the value as is.
Password Type
This type is designed to store passwords or other secure data in TeamCity settings. The value of the password parameter never appears readable in the TeamCity UI, including the settings' screens and the Run Custom Build dialog. The value is also replaced in the build's Parameters tab and build log.
The password value is stored in the configuration files under TeamCity Data Directory. Depending on the server encryption settings, the value is either scrambled or encrypted with a custom key.
Note that if you switch an existing parameter from the Password type to any other type, the original password value will be lost.
Manually Configuring Parameter Specification
You can also configure a parameter's specification manually — using a specially formatted string with the syntax similar to the one used in service messages (typeName key='value').
For example, for the text label, use text label='some label' regex='some pattern'.
Copying Parameter Specification
If you start editing a parameter that has a specification, you can see a link to its raw value in the Edit parameter dialog. Click it to view the specification in its raw form (in the service message format). To use this specification in another build configuration, just copy it from here, and paste it in another configuration.
Modifying Parameter Specification via REST API
You can also view/edit typed parameters' specification via REST API.