Product SiteDocumentation Site

7.2.2. Custom Field Definition

The definition of a custom field includes the following logical attributes:
  • Caption variable name. This value is supplied to the lang_get() API; it is therefore mandatory to set this to a valid PHP identifier (i.e. only letters, numbers and underscores; no spaces) if you intend to translate the field label (see Section 7.2.5, “Localizing Custom Field Names”).

    Note

    If the specified variable is not found in the language files or in custom_strings_inc.php, then it will be displayed as-is.
  • Custom field type (string, numeric, float, enumeration, email, checkbox, radio, list, multi-selection list, date).
    Type 'string' is used for strings of up to 255 characters.
    Type 'numeric' is used for numerical integer values.
    Type 'float' is used for real (float / double) numbers.
    Type 'enumeration' is used when a user selects one entry from a list. The user interface for such type is a combo-box.
    Type 'email' is used for storing email addresses.
    Type 'checkbox' is like enumeration but the list is shown as checkboxes and the user is allowed to tick more than one selection. The default value and the possible value can contain multiple values like 'RED|YELLOW|BLUE' (without the single quote).
    Type 'radio' is like enumeration but the list is shown as radio buttons and the user is allowed to tick on of the options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values.
    Type 'list' is like enumeration but the list is shown as a list box where the user is only allowed to select one option. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values.
    Type 'multi-selection list' is like enumeration but the list is shown as a list box where the user is allowed to select multiple options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'RED|BLUE'. Note that in this case the default value contains multiple values.
    Type 'date' is for date values. The default value can be empty, or {tomorrow}, {yesterday}, {next week}, {last week}, {+3 days}, {-2 days}.
  • Enumeration possible values (eg: RED|YELLOW|BLUE). Use the pipe ('|') character to separate possible values for an enumeration. One of the possible values can be an empty string. The set of possible values can also be calculated at runtime. For example, "=versions" would automatically resolve into all the versions defined for the current project.
  • Default value - see details above for a sample default value for each type.
  • Minimum/maximum length for the custom field value (use 0 to disable). Note that these metrics are not really relevant to custom fields that are based on an enumeration of possible values.
  • Regular expression to use for validating user input (use PCRE syntax).
  • Read Access level: Minimum access level for users to be able to see the value of the custom field.
  • Write Access level: Minimum access level for users to be able to edit the value of the custom field.
  • Display when reporting issues? - If this custom field should be shown on the Report Issue page.
  • Display when updating issues? - If this custom field should be shown on the Update Issue page.
  • Display when resolving issues? - If this custom field should be shown when resolving an issue. For example, a "root cause" custom field would make sense to set when resolving the issue.
  • Display when closing issues? - If this custom field should be shown when closing an issue.
  • Required on Report - If this custom field is a mandatory field on the Report Issue page.
  • Required on Update - If this custom field is a mandatory field on the Update Issue page.
  • Required on Resolve - If this custom field is a mandatory field when resolving an issue.
  • Required on Close - If this custom field is a mandatory field when closing an issue.
If the value of a custom field for a certain defect is not found, the default value is assumed.