Overview

Different teams typically like to capture different information as users report issues, in some cases, the data required is even different from one project to another. Hence, MantisBT provides the ability for managers and administrators to define custom fields as way to extend MantisBT to deal with information that is specific to their teams or their projects. The aim is for this to keep MantisBT native fields to a minimum. Following are some facts about the implementation of custom fields in MantisBT:

• Custom fields are defined system wide.

• Custom fields can be linked to multiple projects.

• The sequence of displaying custom fields can be different per project.

• Custom fields must be defined by users with access level ADMINISTRATOR.

• Custom fields can be linked to projects by users with access level MANAGER or above (by default, this can be configurable).

• Number of custom fields is not restricted.

• Users can define filters that include custom fields.

• Custom fields can be included in View Issues, Print Issues, and CSV exports.

• Enumeration custom fields can have a set of static values or values that are calculated dynamically based on a custom function.

Custom Field Definition

The definition of a custom field includes the following logical attributes:

• Caption variable name (eg: This is the value that is supplied to lang_get() API, or displayed as-is if not found in language file). This should not include any space or any character that would be an invalid PHP identifier.

• 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 th euser 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 ereg() 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 only on Advanced Page? - If set, then this custom field will only show on the advanced pages.

• 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.

All custom fields are currently saved to a field of type VARCHAR(255) in the database. However, in future releases, it is possible to support custom fields of different types (eg: memo, file).

If the value of a custom field for a certain defect is not found, the default value is assumed.

Adding/Editing Custom Fields

• The logged in user needs $g_manage_custom_fields_threshold access level.

• Select "Manage" from the main menu.

• Select "Manage Custom Fields" from the management menu.

• In case of edit, click on the name of an existing custom field to edit its information.

• In case of adding a new one, enter the name of the new custom field then click "New Custom Field".

Added custom fields will not show up in any of the issues until the added custom field is linked to the appropriate projects.

Linking/Unlinking/Ordering Existing Custom Fields in Projects

• The logged in user needs to have access level that is greater than or equal to $g_custom_field_link_threshold and $g_manage_project_threshold.

• Select "Manage" from the main menu.

• Select "Manage Projects".

• Select the name of the project to manage.

• Scroll down to the "Custom Fields" box.

• Select the field to add from the list, then click "Add This Existing Custom Field".

• To change the order of the custom fields, edit the "Sequence" value and click update. Custom fields with smaller values are displayed first.

• To unlink a custom field, click on "Remove" link next to the field. Unlinking a custom field will not delete the values that are associated with the issues for this field. These values are only deleted if the custom field definition is removed (not unlinked!) from the database. This is useful if you decide to re-link the custom field. These values may also re-appear if issues are moved to another project which has this field linked.

Localizing Custom Field Names

It is possible to localize the label for the custom fields. This can be as follows:

• Give the custom field a valid variable name (i.e. start with an alpha character, no spaces, etc) - For example, we will use "my_start_date" for a custom field of type "Date" which stores the "Start Date" for working on an issue.

• Add the localized string for "my_start_date" - This can be done by creating custom_strings_inc.php in the MantisBT root folder and adding the following code to it:

  <?php
  if ( lang_get_current() == 'german' ) {
      $s_my_start_date = 'Start Date XX';  // German translation of Start Date
  } else {
      # Default (use your preferred language as the default)
      $s_my_start_date = 'Start Date';
  }
  ?>

If we would have decided to use start_date as the name of the custom field, then we have used an already localized string from MantisBT standard strings. In this case, there is no need to create the custom_strings_inc.php or to add any strings to it. To check for standard strings, inspect lang/strings_english.txt.

Dynamic default values

Dynamic values for Enumeration Custom Fields

As discussed earlier, one of the possible types of a custom field is "enumeration". This type of custom field allows the user to select one value from a provided list of possible values. The standard way of defining such custom fields is to provide a '|' separated list of possible values. However, this approach has two limitations: the list is static, and the maximum length of the list must be no longer than 255 characters. Hence, the need for the ability to construct the list of possible values dynamically.

Dynamic possible values included by default

MantisBT ships with some dynamic possible values, these include the following:

• =categories - a list of categories defined in the current project (or the project to which the issue belongs).

• =versions - a list of all versions defined in the current project (or the project to which the issue belongs).

• =future_versions - a list of all versions that belong to the current project with released flag set to false.

• =released_versions - a list of all versions that belong to the current project with released flag set to true.

The '=' before the name of the dynamic list of options is used to tell MantisBT that this is a dynamic list, rather than a static list with just one option.

# --------------------
# Construct an enumeration for all categories for the current project.
# The enumeration will be empty if current project is ALL PROJECTS.
# Enumerations format is: "abc|lmn|xyz"
# To use this in a custom field type "=categories" in the possible values field.
function custom_function_override_enum_categories() {
    $t_categories = category_get_all_rows( helper_get_current_project() );

    $t_enum = array();
    foreach( $t_categories as $t_category ) {
        $t_enum[] = $t_category['category'];
    }

    $t_possible_values = implode( '|', $t_enum );

    return $t_possible_values;
}

# --------------------
# To use this in a custom field type "=mine" in the possible values field.
function custom_function_override_enum_mine() {
    $t_enum = array();

    :

    $t_possible_values = implode( '|', $t_enum );

    return $t_possible_values;
}