Typed Parameters
When adding a Configuring Build Parameters (system property, environment variable or configuration parameter), you can extend its definition with a specification that will regulate parameter's control presentation and validation. This specification is the parameter's "meta" information that is used to display the parameter in the Triggering a Custom Build dialog. It allows making a custom build run more user-friendly and usable by non-developers. Consider a simple example. You have a build configuration in which you have a monstrous-looking build parameter that regulates if a build has to include a license or not; can be either true or false; and by default is false. It may be clear for a build engineer, which build parameter regulates license generation and which value it is to have, but it may not be obvious to a regular user. With the build parameter's specification you can make your parameters more readable in the Run Custom Build dialog. Currently you can present parameters in following forms:
simple text field with the ability to validate its value using regular expression;
check box;
select control;
password field.
To add specification to a build parameter, click Edit button in the Spec area when editing/adding a build parameter. All parameters specifications support a number of common properties, such as:
Label: some text that is shown near the control.
Description: some text that is shown below the control containing an explanatory note of the control use.
Display: If hidden is specified, the parameter will not be shown in the Run Custom Build dialog, but will be sent to a build; if prompt is specified, TeamCity will always require a review of the parameter value when clicking the Run button (won't require the parameter if build is triggered automatically); if normal is selected, the parameter will be shown as usual.
Depending on the specification's "type", there are additional settings.
Text | Pattern: In this field specify a Java-style regular expression to validate the field value. |
---|---|
Check box | Check box name: Title of the check box to be displayed in Run Custom Build dialog. Checked value/Unchecked value: Specify values for the parameter to have depending on the check box's state. |
Select | Items: Specify a newline-separated list of items. Use following syntax |
Manually Configuring Parameter Specification
Alternatively, you can manually configure a specification using specially formatted string with syntax similar to the one used in service messages (typeName key='value'
). For example, for text: 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 in another configuration.
Modifying Parameter Specification via REST API
Since TeamCity 8.1, you can view/edit typed parameters specification REST API.