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.

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 ). If the specified variable is not found in the language files or in custom strings, 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. 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.

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.

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. When an issue is moved from one project to another, custom fields that are not defined for the new project are not deleted. These fields will re-appear with their correct values if the issue is moved back to the original project, or if these custom fields are linked to the new project.

It is possible to localize the custom fields' labels. This can be done as follows: Define the custom field (see ), keeping in mind that its name must be a valid PHP identifier. As an example, we will use my_start_date for a custom field of type "Date", storing the date when work on an issue was initiated. Set the localization strings In the main MantisBT directory, locate and edit file custom_strings_inc.php (create it if it does not exist) Localize the custom field's label my_start_date by adding the following code <?php switch( $g_active_language ) { case 'french': $s_my_start_date = 'Date de début'; break; default: # Default language, as defined in config_inc.php # ($g_default_language, English in this case) $s_my_start_date = 'Start Date'; break; } Do NOT call lang_get_current() from custom_strings_inc.php, as doing so will reset the active_language, causing the code to return incorrect translations if the default language is different from English. Always use the $g_active_language global variable instead. Had we decided to use start_date as the custom field's name, then it would not have been necessary to modify custom_strings_inc.php, since MantisBT would have used the existing, already localized string from the standard language files. To check for standard strings, inspect lang/strings_english.txt.

Custom fields of type date can be defaulted to a specific dates or to relative dates. Typically relative dates is the scenario that makes sense in most of the cases. The format for specific dates is an integer which indicates the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT), which is the format consumed by the PHP date() method. The relative scenario expects default values like {tomorrow}, {yesterday}, {+2 days}, {-3 days}, {next week}, etc. The curly brackets indicate that this is a logical value which is then evaluated using the PHP strtotime() function.

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.

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.

If the user selects =versions, the actual custom function that is executed is custom_function_*_enum_versions(). The reason why the "enum_" is not included is to have a fixed prefix for all custom functions used for this purpose and protect against users using custom functions that were not intended for this purpose. For example, you don't want the user to use custom_function_*_issue_delete_notify() which may be overridden by the web master to delete associated data in other databases. Following is a sample custom function that is used to populate a field with the categories belonging to the currently selected project: # -------------------- # 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; } Notice the following: The custom function doesn't take any parameters. The custom function returns the possible values in the format (A|B|C). The custom function uses the current project. The custom function builds on top of the already existing APIs. To define your own function \u201c=mine\u201d, you will have to define it with the following signature: # -------------------- # 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; } Notice "override" in the function name. This is because this method is defined by the MantisBT administrator/webmaster and not part of the MantisBT source. It is OK to override a method that doesn't exist. As usual, when MantisBT is upgraded to future releases, the custom functions will not be overwritten. The difference between the "default" implementation and the "override" implementation is explained in more details in the custom functions section.

Enumerations are used in MantisBT to represent a set of possible values for an attribute. Enumerations are used for access levels, severities, priorities, project statuses, project view state, reproducibility, resolution, ETA, and projection. MantisBT provides the administrator with the flexibility of altering the values in these enumerations. The rest of this topic explains how enumerations work, and then how they can be customised. core/constant_inc.php defines the constants that correspond to those in the enumeration. These are useful to refer to these enumerations in the configs and the code. define( 'VIEWER', 10 ) define( 'REPORTER', 25 ) define( 'UPDATER', 40 ) define( 'DEVELOPER', 55 ) define( 'MANAGER', 70 ) define( 'ADMINISTRATOR', 90 ) config_defaults_inc.php includes the defaults for the enumerations. The configuration options that are defaulted here are used in specifying which enumerations are active and should be used in MantisBT. However, the strings included in the enumerations here are just for documentation purpose, they are not shown to the user (due to the need for localisation). Hence, if an entry in this enumeration is not found in the corresponding localised enumeration (i.e. 70:manager), then it will be printed to the user as @70@. $g_access_levels_enum_string = '10:viewer,25:reporter,40:updater,55:developer,70:manager,90:administrator'; lang/strings_german.txt provide the localised strings (in this case, in german) for enumerations. But again, the master list is the enumeration in the configs, the ones in the language files are just used for finding the localised equivalent for an entry. Hence, if a user changes the config to have only two types of users developers and administrators, then only those will be prompted to the users even if the enumerations in the language files still includes the full list. $s_access_levels_enum_string = '10:Betrachter,25:Reporter,40:Updater,55:Entwickler,70:Manager,90:Administrator'; Let say we want to remove access level "Updater" and add access level "Senior Developer". The file custom_constants_inc.php is supported for the exclusive purpose of allowing administrators to define their own constants while maintaining a simple upgrade path for future releases of MantisBT. Note that this file is not distributed with MantisBT and you will need to create it if you need such customisation. In our example, we need to define a constant for the new access level. define ( 'SENIOR_DEVELOPER', 60 ); In config_inc.php // Remove Updater and add Senior Developer $g_access_levels_enum_string = '10:viewer,25:reporter,55:developer,60:senior_developer,70:manager,90:administrator'; // Give access to Senior developers to create/delete custom field. $g_manage_custom_fields_threshold = SENIOR_DEVELOPER; The file custom_strings_inc.php is introduced for a similar reason to that of custom_constants_inc.php, which is to define custom strings. The advantage of defining them here is to provide a simple upgrade path, and avoid having to re-do the changes when upgrading to the next MantisBT release. Note that you will need to create this file if you need such customisation. The file is automatically detected and included by MantisBT code. # Note that we don't have to remove the Updater entry from the localisation file if the current language is 'english' ) { $s_access_levels_enum_string = '10:Betrachter,25:Reporter,40:Updater,55:Entwickler,60:Senior Developer,70:Manager,90:Administrator'; } We have covered how enumerations work in general, and how to customise one of them. If you are interested in customising other enumerations, a good starting point would be to go to "MantisBT Enum Strings" section in config_defaults_inc.php. This section defines all enumerations that are used by MantisBT. For versions that are older than 0.18.0, custom_*_inc.php files are not supported, and hence you will need to change in the actual constants / language files directly.

See Email in the Configuration section. Examples: Notify only managers of new issues. $g_notify_flags['new']['threshold_min'] = MANAGER; $g_notify_flags['new']['threshold_max'] = MANAGER; Notify Developers and managers of all project events, except, exclude developers from the 'closed' events. $g_default_notify_flags['threshold_min'] = DEVELOPER; $g_default_notify_flags['threshold_max'] = MANAGER; $g_notify_flags['closed']['threshold_max'] = MANAGER; $g_notify_flags['closed']['threshold_max'] = MANAGER; Exclude those who contributed issue notes from getting messages about other changes in the issue. $g_default_notify_flags['bugnotes'] = OFF; Exclude those monitoring issues from seeing the 'closed' message $g_notify_flags['closed']['monitor'] = OFF; Only notify developers when issue notes are added. $g_notify_flags['bugnote']['threshold_min'] = DEVELOPER; $g_notify_flags['bugnote']['threshold_max'] = DEVELOPER; Notify managers of changes in sponsorship. $g_notify_flags['sponsor']['threshold_max'] = MANAGER; $g_notify_flags['sponsor']['threshold_max'] = MANAGER; Notify originator and managers of changes in ownership ("Assigned To:"). $g_notify_flags['owner']['threshold_max'] = MANAGER; $g_notify_flags['owner']['threshold_max'] = MANAGER; $g_notify_flags['owner']['reporter'] = ON; I'm paranoid about mail. Only send information on issues to those involved in them. Don't send mail people already know about. Also send new issue notifications to managers so they can screen them. $g_mail_receive_own = OFF; $g_default_notify_flags = array('reporter' => ON, 'handler' => ON, 'monitor' => ON, 'bugnotes' => ON, 'threshold_min' => NOBODY, 'threshold_max' => NOBODY); $g_notify_flags['new']['threshold_min'] = MANAGER; $g_notify_flags['new']['threshold_max'] = MANAGER; How do I replace the $g_to_email configuration variable to log all messages to an email logger. You will need to create a dummy user with the appropriate access level for the notices you want to log. Once this user is added to projects, they will receive mail using the appropriate rules.

This section describes how to add a custom status. Define a constant to map the new status to. In the main MantisBT directory, locate and edit file custom_constants_inc.php; (create it if it does not exist) <?php # Custom status code define( 'TESTING', 60 ); Define the new status in the enumeration, as well as the corresponding color code. In the main mantisbt directory, edit your config_inc.php # Revised enum string with new 'testing' status $g_status_enum_string = '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,60:testing,80:resolved,90:closed'; # Status color additions $g_status_colors['testing'] = '#ACE7AE'; Note that the key in the $g_status_colors array must be equal to the value defined for the new status code in $g_status_enum_string. Define the required translation strings for the new status, for each language used in the installation. s_status_enum_string: status codes translation (refer to the original language strings for standard values) s_XXXX_bug_title: title displayed in the change status page s_XXXX_bug_button: label for the submit button in the change status page s_email_notification_title_for_status_bug_XXXX: title for notification e-mails where XXXX is the name of the new status as it was defined in g_status_enum_string above. If XXXX contains spaces, they should be replaced by underscores in the language strings names (e.g. for '35:pending user', use '$s_pending_user_bug_button') In the main mantisbt directory, locate and edit file custom_strings_inc.php; (create it if it does not exist) <?php # Translation for Custom Status Code: testing switch( $g_active_language ) { case 'french': $s_status_enum_string = '10:nouveau,20:commentaire,30:accepté,40:confirmé,50:affecté,60:à tester,80:résolu,90:fermé'; $s_testing_bug_title = 'Mettre le bogue en test'; $s_testing_bug_button = 'A tester'; $s_email_notification_title_for_status_bug_testing = 'Le bogue suivant est prêt à être TESTE.'; break; default: # english $s_status_enum_string = '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,60:testing,80:resolved,90:closed'; $s_testing_bug_title = 'Mark issue Ready for Testing'; $s_testing_bug_button = 'Ready for Testing'; $s_email_notification_title_for_status_bug_testing = 'The following issue is ready for TESTING.'; break; } Do NOT call lang_get_current() from custom_strings_inc.php, as doing so will reset the active_language, causing the code to return incorrect translations if the default language is different from English. Always use the $g_active_language global variable instead. Add the new status to the workflow as required. This can either be done from the Manage Workflow Transitions page or by manually editing config_inc.php as per the example below: $g_status_enum_workflow[NEW_] ='30:acknowledged,20:feedback,40:confirmed,50:assigned,80:resolved'; $g_status_enum_workflow[FEEDBACK] ='30:acknowledged,40:confirmed,50:assigned,80:resolved'; $g_status_enum_workflow[ACKNOWLEDGED] ='40:confirmed,20:feedback,50:assigned,80:resolved'; $g_status_enum_workflow[CONFIRMED] ='50:assigned,20:feedback,30:acknowledged,80:resolved'; $g_status_enum_workflow[ASSIGNED] ='60:testing,20:feedback,30:acknowledged,40:confirmed,80:resolved'; $g_status_enum_workflow[TESTING] ='80:resolved,20:feedback,50:assigned'; $g_status_enum_workflow[RESOLVED] ='90:closed,20:feedback,50:assigned'; $g_status_enum_workflow[CLOSED] ='20:feedback,50:assigned'; Check and update existing workflow configurations If you do not perform this step and have existing workflow definitions, it will not be possible to transition to and from your new status. Go to the Workflow Transitions page (manage_config_workflow_page.php), and update the workflow as appropriate. Make sure that you have picked the correct Project in the selection list). Hint: to identify whether you have any workflows that should be updated, open the Manage Configuration Report page (adm_config_report.php) and filter on 'All Users', [any] project and config option = 'status_enum_workflow'. All of the listed projects should be reviewed to eventually include transitions to and from the newly added states.

Custom functions are used to extend the functionality of MantisBT by integrating user-written functions into the issue processing at strategic places. This allows the system administrator to change the functionality without touching MantisBT's core. Default Custom Functions are defined in the API file core/custom_function_api.php , and are named custom_function_default_descriptive_name, where descriptive_name describes the particular function. See below for a description of the specific functions. User versions of these functions (overrides) are named like custom_function_override_descriptive_name, and placed in a file called custom_functions_inc.php that must be saved in MantisBT's root directory (This is the same place where the config_inc.php file resides). In normal processing, the system will look for override functions and execute them instead of the provided default functions. The simplest way to create a custom function is to copy the default one from the api to your override file (custom_functions_inc.php), and rename it (i.e. replacing 'default' by 'override'). The specific functionality you need can then be coded into the override function.

Refer to core/custom_functions_api.php for further details. Custom Function Name Description Return value custom_function_default_auth_can_change_password() Determines whether MantisBT can update the password True if yes, False if not custom_function_default_changelog_include_issue( $p_issue_id ) Determines whether the specified issue should be included in the Changelog or not. True to include, False to exclude custom_function_default_changelog_print_issue( $p_issue_id, $p_issue_level = 0 ) Prints one entry in the Changelog None custom_function_default_checkin( $p_issue_id, $p_comment, $p_file, $p_new_version, $p_fixed ) Register a checkin in source control by adding a history entry and a note None custom_function_default_enum_categories() Build a list of all categories for the current project Enumeration, delimited by "|" custom_function_default_enum_future_versions() Build a list of all future versions for the current project Enumeration, delimited by "|" custom_function_default_enum_released_versions() Build a list of all released versions for the current project Enumeration, delimited by "|" custom_function_default_enum_versions() Build a list of all versions for the current project Enumeration, delimited by "|" custom_function_default_format_issue_summary( $p_issue_id, $p_context = 0 ) Format the bug summary Formatted string custom_function_default_get_columns_to_view( $p_columns_target = COLUMNS_TARGET_VIEW_PAGE, $p_user_id = null ) Defines which columsn should be displayed Array of the column names custom_function_default_issue_create_notify( $p_issue_id ) Notify after an issue has been created In case of invalid data, this function should call trigger_error() custom_function_default_issue_create_validate( $p_new_issue_data ) Validate field settings before creating an issue In case of invalid data, this function should call trigger_error() custom_function_default_issue_delete_notify( $p_issue_data ) Notify after an issue has been deleted In case of invalid data, this function should call trigger_error() custom_function_default_issue_delete_validate( $p_issue_id ) Validate field settings before deleting an issue In case of invalid data, this function should call trigger_error() custom_function_default_issue_update_notify( $p_issue_id ) Notify after an issue has been updated In case of invalid data, this function should call trigger_error() custom_function_default_issue_update_validate( $p_issue_id, $p_new_issue_data, $p_bugnote_text ) Validate field issue data before updating In case of invalid data, this function should call trigger_error() custom_function_default_print_bug_view_page_custom_buttons( $p_bug_id ) Prints the custom buttons on the current view page None custom_function_default_print_column_title( $p_column, $p_columns_target = COLUMNS_TARGET_VIEW_PAGE ) Print a column's title based on its name None custom_function_default_print_column_value( $p_column, $p_bug, $p_columns_target = COLUMNS_TARGET_VIEW_PAGE ) Print a column's value based on its name None custom_function_default_roadmap_include_issue( $p_issue_id ) Determines whether the specified issue should be included in the Roadmap or not. True to include, False to exclude custom_function_default_roadmap_print_issue( $p_issue_id, $p_issue_level = 0 ) Prints one entry in the Roadmap None

The following function is used to validate an issue before it is resolved. status == RESOLVED ) { if ( $p_bug_data->resolution == OPEN ) { error_parameters( 'the resolution cannot be open to resolve the issue' ); trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR ); } $t_version_count = count( version_get_all_rows( $p_bug_data->project_id ) ); if( ( $t_version_count > 0 ) && ( $p_bug_data->fixed_in_version == '' ) ) { error_parameters( 'fixed in version must be set to resolve the issue' ); trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR ); } } } ?>]]> The errors will also need to be defined, by modifying the following files custom_constants_inc.php define( 'ERROR_VALIDATE_FAILURE', 2000 ); custom_strings_inc.php $MANTIS_ERROR['ERROR_VALIDATE_FAILURE'] = 'This change cannot be made because %s';