What is MantisBT?

MantisBT is a web based bug tracking system that was first made available to the public in November 2000. Over time it has matured and gained a lot of popularity, and now it has become one of the most popular open source bug/issue tracking systems. MantisBT is developed in PHP, with support to multiple database backends including MySQL, MS SQL, PostgreSQL and DB2.

MantisBT, as a PHP script, can run on any operating system that is supported by PHP and has support for one of the DBMSes that are supported. MantisBT is known to run fine on Windows, Linux, OS/2, Mac OS X, System i and a variety of Unix operating systems.

Who should read this manual?

This manual is targeted for the person responsible for evaluating, installing and maintaing MantisBT in a company. Typically we refer to this person as the MantisBT administrator.

License

MantisBT is released under the terms of GNU General Public License (GPL). MantisBT is free to use and modify. It is free to redistribute as long as you abide by the distribution terms of the GPL.

How to get it?

MantisBT is available in several Linux distributions including: Debian, Ubuntu, Fedora, Gentoo, Frugalware and others. Hence, if you are running Linux, start by checking if your distribution has a package for MantisBT. If not, or if the package is not up-to-date with the latest MantisBT version, then you may want to download it directly from here.

For Windows, Mac OS X and other operating systems, use the link provided above to download MantisBT. The download is compressed in tar.gz or zip format. Both formats can be unpacked using tools like 7-Zip (in case of Windows).

Note that at any point in time there are typically two "latest" MantisBT releases that are available for download. The latest production release (stable), and the latest development release which can be an alpha or a release candidate. It is not recommended to use development releases in production specially if it is still in the alpha stage unless the administrator is familiar with PHP and is able to troubleshoot and fix any issues that may arise.

About the Name

When initially seeking to name this project Ken ran into a problem every programmer encounters. What is a good name? It has to be descriptive, unique, and not too verbose. Additionally having multiple meanings would be a nice touch. Quickly ruled out were php*Something* names which, incidentally, although popular, do not seem to be condoned by the PHP Group developers. Drawing inspiration from Open Source projects like Apache, Mozilla, Gnome, and so forth resulted in two eventual choices: Dragonfly and Mantis. Dragonfly was already the name of a webmail package. So the name became Mantis.

Praying Mantis are insects that feed primarily on other insects and bugs. They are extremely desirable in agriculture as they devour insects that feed on crops. They are also extremely elegant looking creatures. So, we have a name that is fairly distinctive and descriptive in multiple ways. The BT suffix stands for "Bug Tracker" and distinguishes this project from general usage of the word Mantis. However, over time the project was typically referred to as Mantis.

History

Kenzaburo Ito and a friend originally created a bug tracker as an internal tool for their pet project. A search for good, free packages came up with nothing suitable so they wrote their own. After a rewrite and cleanup it was made available to the public via the GNU General Public License (GPL). The GPL was chosen partly because of his belief that development tools should be cheap or free. In 2002, Ken was joined by Jeroen Latour, Victor Boctor and Julian Fitzell to be the administrators and the core development team of MantisBT. This marks a new era in MantisBT lifetime where it is now a team project.

Support

There are plenty of resources to help answer support queries. Following are the main ones:

• Forums - The forums are one of the most popular destinations for getting MantisBT support. Start off by searching the forums for your questions, if not found, then go ahead and submit a question.

• Mailing lists - Available mailing lists are "mantisbt-announce" for announcements, "mantisbt-dev" for development issues, mantisbt-lang for localization and "mantisbt-help" for general help/support questions. There are public archives for such mailing lists. Note that only members of the mailing lists can post to them, hence, subscribe to the lists before you attempt to email them.

• IRC - The IRC channel is mainly used by developers to engage in in-person discussion. The recommended tool for IRC is XChat (for Linux), XChat 2 (for Windows). However, you can also use Web Chat to connect to IRC via your web browser. This is also useful when your work firewall blocks the IRC port (although there are other workarounds involving tunneling to fix this issue). Many people prefer to use IRC to ask questions to the developers and other users who are in the IRC channel. The IRC channel logs are archived and made available on the web. (TODO: add irc logs link)

• Wiki - The MantisBT Wiki has information related to "How To (recipes)", FAQ, feature requirements, etc.

• Search - A good way for locating an answer for your question or finding more information about a topic is to search across all MantisBT website and the Internet via Google or Bing.

It is important to note that support questions should not be sent directly to MantisBT developers or through the MantisBT contact us pages. Use of "Contact Us" page or emailing the developer directly is available if you are after a paid support or consulting service.

MantisBT News

There are several ways to keep up to date with MantisBT news. These include:

• mantisbt-announce mailing list is a very low traffic list that is used for major announcements, typically announcements about releases. All MantisBT users are encouraged to subscribe to this mailing list. The average traffic should be no more than one to two posts per month.

• MantisBT Blog is used to communicate announcements about new releases, topics relating to MantisBT, etc. Users are encouraged to subscribe to the RSS feed to know when new posts are posted there.

• Twitter is used to notify users about up-to-date details about what is happening with MantisBT development. For example, a Twitter update is automatically posted by the official bug tracker whenever an issue is resolved. Twitter users are encouraged to follow "mantisbt".

Versioning

The release numbering convention we use is major.minor.micro (eg. 1.2.0rc1).

• Major - Indicates a very large change in the core package. Rewrites or major milestones.

• Minor - Significant amount of feature addition/modification.

• Micro - Mostly bug fixes and maintenance releases.

• Suffix - rc1 for first release candidate, a1 for alpha 1, etc.

Overview

The table below contains a high-level overview of the processes. Refer to the corresponding sections for details.

System Requirements

Pre-installation / upgrade tasks

These tasks cover the download and deployment of MantisBT, and should be performed prior to any new installation or upgrade.

1. Download MantisBT

2. Transfer the downloaded file to your webserver

   This can be done using whatever method you like best (ftp, scp, etc). You will need to telnet/ssh into the server machine for the next steps.

3. Extract the release

   It is highly recommended to maintain a separate directory for each release. This not only avoids mismatch between versions, (files may have been added or removed) but also provides an easy path to downgrade your installation, should you need to.

   The usual command is (1 step):

   tar -xzf filename.tar.gz

   OR (2 steps):

   gunzip filename.tar.gz
   tar -xf filename.tar

   Other file archiving tools such as 7-Zip should also be able to handle decompression of the archive.

   The extraction process should create a new directory like mantisbt-1.2.x

4. Rename the directory

   For new installations, you may want to rename the directory just created to something simpler, e.g. mantisbt

   mv mantisbt-1.2.x mantisbt

New Installation

This chapter explains how to perform a new installation of MantisBT.

Start by checking the system requirements and installing the appropriate version of required software.

Once that is done, execute the installation script. From your web browser, access

http://yoursite/mantisbt/admin/install.php

1. The script checks basic parameters for the web server

2. Provide required information for the installation

   • database type

   • database server hostname

   • user and password

     Required privileges: SELECT, INSERT, UPDATE, and DELETE

   • high-privileged database account

     Additional privileges required: INDEX, CREATE, ALTER, and DROP

     If this account is not specified, the database user will be used.

3. Click the Install/Upgrade Database button

4. The script creates the database and tables.

   The default Administrator user account is created at this stage, to allow the initial login and setup of MantisBT.

5. The script attempts to write a basic config_inc.php file to define the database connection parameters.

   This operation may fail if the web server's user account does not have write permissions to the directory (which is recommended for obvious security reasons). In this case, you will have to manually create the file and copy/paste the contents from the page.

6. The script perform post installation checks on the system.

   Review and correct any errors.

Upgrading

This chapter explains how to upgrade an existing MantisBT installation.

Start by Performing the steps described in Pre-installation tasks above.

1. Put the site down for maintenance

   cp mantis_offline.php.sample mantis_offline.php

   This will prevent users from using the system while the upgrade is in progress.

2. Always Backup your code, data and config files before upgrading !

   This includes your Mantis directory, your attachments, and your database. Refer to the Backups section for details.

3. Copy the configuration files

   To preserve your system settings, you should copy the files listed below to the new directory, as well as any other custom files such as logo, favicon, css, etc.

   config_inc.php custom_strings_inc.php custom_constants_inc.php custom_functions_inc.php

4. Execute the upgrade script. From your web browser, access

   http://yoursite/mantisbt-NEW/admin/install.php

   where mantisbt-NEW is the name of the directory where the new release was extracted

5. Provide required information for the upgrade

   • high-privileged database account

     Additional privileges required: INDEX, CREATE, ALTER, and DROP

     If this account is not specified, the database user will be used.

6. Click the Install/Upgrade Database button

7. At the end of the upgrade, review and correct any warnings or errors.

Configure your installation

There are many settings that you can adjust to configure and customize MantisBT. Refer to the Configuration section, as well as the config_default_inc.php file for in depth explanations of the available options. Check out also the Customizing MantisBT section for further options to personalize your installation.

This step is normally only required for new installations, but when upgrading you may want to review and possibly customize any new configuration options.

Open or create the file config_inc.php in an editor and add or modify any values as required. These will override the default values.

You may want to use the provided config_inc.php.sample file as a starting point.

WARNING: you should never edit the config_default_inc.php file directly, as it could cause issues with future upgrades.

Post-installation and upgrade tasks

Instructions in this section are common to both new installations and upgrades, and should be applied after completing either process.

1. Test your configuration

   Load up admin/check.php to validate if everything is setup correctly.

   NOTE (for PHP 5.2 only): check.php sometimes reports the value of register_globals incorrectly. To confirm the correct value, Create a page with this line in it:

   <?php phpinfo(); ?>

   save it with a .php extension and load it up in your web browser.

2. Delete the admin folder

   For security reasons, the scripts within this directory should not be accessible on a live MantisBT site or on any installation that is accessible via the Internet.

   Once you have confirmed that the install/upgrade was successful, you should delete this directory

   rm -r admin

Post-installation tasks

Instructions in this section should only be applied after a new installation

1. Login to your bugtracker

   Use the default Administrator account. The id and password are administrator / root.

2. Create a new Administrator account

   Go to Manage > Manage Users and create a new account with 'administrator' access level.

3. Disable or delete the default Administrator account

4. Create a new Project

   Go to Manage > Manage Projects and create a new project

Post-upgrade tasks

Instructions in this section should only be applied after upgrading an existing installation.

1. Test the new release

   Perform any additional testing as appropriate to ensure the new version does not introduce any regressions.

2. Switch the site to the new version

   The commands below should be executed from the web root (or wherever the mantisbt scripts are installed) and assume that the "live" directory (old version) is named mantisbt and the new release directory is mantisbt-1.2.x.

   mv mantisbt mantisbt-old
   mv mantisbt-1.2.x mantisbt

3. Put the site back on line

   rm mantis_offline.php

   This should be the final step in the upgrade process, as it will let users login again.

Backups

It is strongly recommended to backup your MantisBT database on a regular basis. The method to perform this operation depends on which RDBMS you use.

Backups are a complex subject, and the specificities of implementing and handling them for each RDBMS are beyond the scope of this document. For your convenience, the section below provides a simple method to backup MySQL databases.

You should also consider implementing backups of your MantisBT code (which includes your configs and possibly customization), as well as issue attachments (if stored on disk) and project documents.

!!! Backups should always be performed before an upgrade !!!

mysqldump -u<username> -p<password> <database name> > <output file>

mysql -u<username> -p<password> <database name> < <input file>

Uninstall

It is recommended that you make a backup in case you wish to use your data in the future. See the Backups page for details.

To uninstall MantisBT:

• Delete the MantisBT directory and all files and subdirectories.

• Drop all MantisBT tables from the database, these can be identified by the configured prefix for the installation. The default prefix is 'mantis'.

• Remove any customizations or additions that you may have made.

Creating User Accounts

In MantisBT, there is no limit on the number of user accounts that can be created. Typically, installations with thousands of users tend to have a limited number of users that have access level above REPORTER.

By default users with ADMINISTRATOR access level have access to create new user accounts. The steps to do that are:

• Click "Manage" on Main Menu.

• Click "Manage Users" (if not selected by default).

• Click "Create New Account" button just below the alphabet key.

• Enter user name, email address, global access level (more details about access levels later). Other fields are optional.

• Click "Create Users".

Creating a user triggers the following actions:

• Creating a user in the database.

• If email notifications ($g_enable_email_notification) is set to ON, then the user will receive an email allowing them to activate their account and set their password. Otherwise, the account will be created with a blank password.

• If email notifications ($g_enable_email_notification) is set to ON, users with access level about $g_notify_new_user_created_threshold_min will get a notification that a user account has been created. Information about the user like user name and email address are provided. The IP of the user that created the account is also included.

When the 'Protected' flag is set on a user account, it indicates that the account is a shared account (e.g. demo account) and hence users logged using such account will not be allowed to change account preferences and profile information.

The anonymous user account specified with the $g_anonymous_account option will always be treated as a protected user account. When you are creating the anonymous user account, the 'Protected' flag is essentially ignored because the anonymous user is always treated as a protected user.

Enabling/Disabling User Accounts

The recommended way of retiring user accounts is to disable them. Scenarios where this is useful is when a person leaves the team and it is necessary to retire their account.

Once an account is disabled the following will be enforced:

• All currently active sessions for the account will be invalidated (i.e. automatically logged out).

• It will no longer be possible login using this account.

• No further email notifications will be sent to the account once it is disabled.

• The user account will not show anymore in lists like "assign to", "send reminder to", etc.

The disabling process is totally reversible. Hence, the account can be re-enabled and all the account history will remain intact. For example, the user will still have issues reported by them, assigned to them, monitored by them, etc.

Deleting User Accounts

Another way to retire user accounts is by deleting them. This approach is only recommended for accounts that have not been active (i.e. haven't reported issues). Once the account is deleted, any issues or actions associated with such account, will be associated with user123 (where 123 is the code of the account that was deleted). Note that associated issues or actions are not deleted.

As far as the underlying database, after the deletion of a user, records with the user id as a foreign key will have a value that no longer exists in the users table. Hence, any tools that operate directly on the database must take this into consideration.

By default administrators are the only users who can delete user accounts. They can delete accounts by clicking Manage, Manage Users, locating the user to be deleted and opening it details page, then clicking on the "Delete User" button which deletes the user.

Note that "Deleting Users" is not a reversible process. Hence, if it is required to re-add the user account, it is not possible to recreate the user account so that it gets the same ID and hence retains its history. However, manually creating a record in the users table with the same id, can possibly do that. However, this approach is not recommended or supported.

User Signup

For open source and freeware projects, it is very common to setup MantisBT so that users can signup for an account and get a REPORTER access by default (configurable by the $g_default_new_account_access_level configuration option). The signup process can be enabled / disabled using the $g_allow_signup configuration option, which is enabled by default.

If email notifications ($g_enable_email_notification) is set to ON, users with access level about $g_notify_new_user_created_threshold_min will get a notification that a user account has been created. Information about the user like user name, email address, IP address are included in the email notification.

Forgot Password and Reset Password

It is pretty common for users to forget their password. MantisBT provides two ways to handle such scenario: "Forgot Password" and "Reset Password".

"Forgot Password" is a self service scenario where users go to the login page, figure out they don't remember their password, and then click the "Lost your password?" link. Users are then asked for their user name and email address. If correct, then they are sent an email with a link which allows them to login to MantisBT and change their password.

"Reset Password" scenario is where a user reports to the administrator that they are not able to login into MantisBT anymore. This can be due to forgetting their password and possibly user name or email address that they used when signing up. The administrator then goes to Manage, Manage Users, locates the user account and opens its details. Under the user account details, there is a "Reset Password" button which the administrator can click to reset the password and trigger an email to the user to allow them to get into MantisBT and set their password. In the case where email notifications are disabled, resetting password will set the password to an empty string.

Changing Password

Users are able to change their own passwords (unless their account is "protected"). This can be done by clicking on "My Account", and then typing the new password in the "Password" and "Confirm Password" fields, then clicking "Update User". Changing the password automatically invalidates all logged in sessions and hence the user will be required to re-login. Invalidating existing sessions is very useful in the case where a user going onto a computer, logs into MantisBT and leaves the computer without logging out. By changing the password from another computer, the session on the original computer automatically becomes invalidated.

Pruning User Accounts

The pruning function allows deleting of user accounts for accounts that have been created more than a week ago, and they never logged in. This is particulary useful for users who signed up with an invalid email or with a typo in their email address address.

The account pruning can be done by administrators by going to "Manage", "Manage Users", and clicking the "Prune Accounts" button inside the "Never Logged In" box.

Authorization and Access Levels

MantisBT uses access levels to define what a user can do. Each user account has a global or default access level that is associated with it. This access level is used as the access level for such users for all actions associated with public projects as well as actions that are not related to a specific project. Users with global access level less than $g_private_project_threshold will not have access to private projects by default.

The default access levels shipped with MantisBT out of the box are VIEWER, REPORTER, UPDATER, DEVELOPER, MANAGER and ADMINISTRATOR. Each features has several configuration options associated with it and identifies the required access level to do certain actions. For example, viewing an issue, reporting an issue, updating an issue, adding a note, etc.

For example, in the case of reporting issues, the required access level is configurable using the $g_report_bug_threshold configuration option (which is defaulted to REPORTER). So for a user to be able to report an issue against a public project, the user must have a project-specific or a global access level that is greater than or equal to REPORTER. However, in the case of reporting an issue against a private project, the user must have project specific access level (that is explicitly granted against the project) that is higher than REPORTER or have a global access level that is higher than both $g_private_project_threshold and $g_report_bug_threshold.

Note that project specific access levels override the global access levels. For example, a user may have REPORTER as the global access level, but have a MANAGER access level to a specific project. Or a user may have MANAGER as the global access level by VIEWER access to a specific project. Access levels can be overriden for both public and private projects. However, overriding access level is not allowed for users with global access ADMINISTRATOR.

Each feature typically has multiple access control configuration options to defines what access level can do certain operations. For example, adding a note may require REPORTER access level, updating a note my require DEVELOPER access level, unless the own was owned by the same user and in this case REPORTER access level. Such threshold configuration options can be set to a single access level, which means users with such threshold and above are authorized to do such action. The other option is to specify an array of access level which indicates that users with the explicitly specific thresholds are allowed to do such actions.

It is also worth mentioning that the access levels are defined by the $g_access_levels_enum_string configuration option, and it is possible to customize such list. The default value for the available access levels is '10:viewer, 25:reporter, 40:updater, 55:developer, 70:manager, 90:administrator'. The instructions about how to customize the list of access levels will be covered in the customization section.

Auto Creation of Accounts on Login

In some cases MantisBT is setup in a way, where it allows users that already exists in a directory or another application to be automatically authenticated and added to MantisBT. For example, a company may setup their MantisBT installation in a way, where its staff members that are already registered in their LDAP directory, should be allowed to login into MantisBT with the same user name and password. Another example, is where MantisBT is integrated into some content management system, where it is desired to have a single registration and single sign-on experience. In such scenarios, once a user logs in for the first time, a user account is automatically created for them, although the password verification is still done against LDAP or the main users repository.

User Preferences

Users can fine tune they way MantisBT interacts with them via modifying their user preferences. User preferences can only be managed by users and are not available for the administrators to tweak. The administrators can only tweak the default value for such preferences. However, once a user account is created, it is then the responsibility of the user to manage their own preferences. The user preferences include the following:

• Default Project: A user can choose the default project that is selected when the user first logs in. This can be a specific project or "All Projects". For users that only work on one project, it would make sense to set such project as the default project (rather than "All Projects"). The active project is part of the filter applied on the issues listed in the "View Issues" page. Also any newly reported issues will be associated with the active project.

• Refresh Delay: The refresh delay is used to specify the number of seconds between auto-refreshes of the View Issues page.

• Redirect Delay: The redirect delay is the number of seconds to wait after displaying flash messages like "Issue created successfully", and before the user gets redirected to the next page.

• Notes Sort Order: The preference relating to how notes should be ordered on an issue is viewed or in email notifications. The ascending order is where notes are ordered so that ordered notes appear before newer notes, the descending order is the reverse.

• Email on New: If unticked, then email notifications relating to creation of a new issue would be disabled. Note that the preference is only used to disabled notifications that as per the administrator's configuration, this user would have qualified to receive them.

• Email on Change of Handler: TODO - is this preference used?

• Email on Feedback: TODO - is this preference used?

• Email on Resolved: TODO

• Email on Closed: TODO

• Email on Reopened: TODO

• Email on Note Added: TODO

• Email on Status Change: TODO

• Email on Priority Change: TODO - is this preference used?

• Email Notes Limit: This preference can be used to limit the number of issue notes to view or to be included in an email notifications. Specifying N here means that the latest N notes will be included. The value 0 causes all notes to be included.

• Language: The preferred language of the user. This language is used by the GUI and in email notifications. Note that MantisBT uses UTF8 for encoding the data, and hence, the user can be interacting with MantisBT user interface in Chinese while logging issue data in German.

User Profiles

A user profile describes an environment that the user uses to run the software for which issues are being tracked. The profile information include "Platform", "Operating System", "OS Version", and "Additional Description". Each user has access to profiles that they create (can be multiple), in addition to global ones that are shared created by other users. When reporting issues, users can elect to enter information like platform, operating system, version manually, or they can choose from the list of profiles that are already defined.

Global profiles are typically used by the administrator to define a set of standard profiles that are typically used by the MantisBT users. This makes it easier for the users to use such profiles without having to define create them. The access level required for users to be able to create global profiles is configured by the $g_manage_global_profile_threshold configuration option and it is defaulted to MANAGER.

Issue Creation

The life cycle of an issue starts with its creation. An issue can be created via one of the following channels:

• MantisBT Web Interface - This is where a user logs into MantisBT and reports a new issue.

• SOAP API - Where an application automatically reports an issue into MantisBT using the SOAP API web services interfaces. For example, the nighlty build script can automatically report an issue if the build fails.

• Email - This is not supported out of the box, but there are existing MantisBT patches that would listen to emails on pre-configured email addresses and adds them to the MantisBT database.

• Others - There can be several other ways to report issues. For example, applications / scripts that directly injects issues into MantisBT database (not recommended, except for one-off migration scripts), or PHP scripts that use the core MantisBT API to create new issues.

Issue Statuses

An important part of issue tracking is to classify issues as per their status. Each team may decide to have a different set of categorization for the status of the issues, and hence, MantisBT provides the ability to customize the list of statuses. MantisBT assumes that an issue can be in one of three stages: opened, resolved and closed. Hence, the customized statuses list will be mapped to these three stages. For example, MantisBT comes out of the box with the following statuses: new, feedback, acknowledged, confirmed, assigned, resolved and closed. In this case "new" -> "assigned" map to opened, "resolved" means resolved and "closed" means closed.

Following is the explanation of what the standard statuses that are shipped with MantisBT means.

• New - This is the landing status for new issues. Issues stay in this status until they are assigned, acknowledged, confirmed or resolved. The next status can be "acknowledged", "confirmed", "assigned" or "resolved".

• Acknowledged - This status is used by the development team to reflect their agreement to the suggested feature request. Or to agree with what the reporter is suggesting in an issue report, although they didn't yet attempt to reproduce what the reporter is referring to. The next status is typically "assigned" or "confirmed".

• Confirmed - This status is typically used by the development team to mention that they agree with what the reporter is suggesting in the issue and that they have confirmed and reproduced the issue. The next status is typically "assigned".

• Assigned - This status is used to reflect that the issue has been assigned to one of the team members and that such team member is actively working on the issue. The next status is typically "resolved".

• Resolved - This status is used to reflect that the issue has been resolved. An issue can be resolved with one of many resolutions (customizable). For example, an issue can be resolved as "fixed", "duplicate", "won't fix", "no change required", etc. The next statuses are typically "closed" or in case of the issue being re-opened, then it would be "feedback".

• Closed - This status reflects that the issue is completely closed and no further actions are required on it. It also typically hides the issue from the View Issues page. Some teams use "closed" to reflect sign-off by the reporter and others use it to reflect the fact that the fix has been released to customers.

Workflow

Now that we have covered how an issue gets created, and what are the different statuses during the life cycle of such issues, the next step is to define the workflow. The workflow dictates the valid transitions between statuses and the user access level required of the user who triggers such transitions; in other words, how issues move from one status to another and who is authorized to trigger such transitions.

MantisBT provides the ability for teams to define their own custom workflow which works on top of their custom status.

$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]       ='80:resolved,20:feedback,30:acknowledged,40:confirmed';
$g_status_enum_workflow[RESOLVED]       ='90:closed,20:feedback,50:assigned';
$g_status_enum_workflow[CLOSED]         ='20:feedback,50:assigned';

Database

The database settings must be set in order for the package to work properly. These settings should be provided to you by your system administrator or your hosting company.

Path

These path settings are important for proper linking within MantisBT. In most scenarios the default values should work fine, and you should not need to override them.

Webserver

Configuration Settings

Signup and Lost Password

Email

MantisBT uses flags and a threshold system to generate emails on events. For each new event, email is sent to:

• the reporter, qualified by the notify flag 'reporter' below

• the handler (or Assigned to), qualified by the notify flag 'handler' below

• anyone monitoring the bug, qualified by the notify flag 'monitor' below

• anyone who has ever added a bugnote the bug, qualified by the notify flag 'bugnotes' below

• anyone assigned to the project whose access level is greater than or equal to the notify flag 'threshold_min' and less than or equal to the notify flag 'threshold_max' below

From this list, those recipients who meet the following criteria are eliminated:

• the originator of the change, if $g_email_receive_own is OFF

• the recipient either no longer exists, or is disabled

• the recipient has turned their email_on_<new status> preference OFF

• the recipient has no email address extered

Version

Language

If a string does not exist in the active language, the English string is used instead.

Display

Time

Date

These variables control how the date is displayed (default is 'US' formatting). Go to the date() function in PHP online manual for detailed instructions on date formatting.

News

These options are used to control the query that selects the news entries to be displayed.

Default Preferences

These settings are used as the default values for preferences for new users. Each user can override these settings through the user preferences form. Default language is set to default site language ($g_default_language).

See also: Email Notifications

Summary

These are the settings that are used to configuration options related to the Summary page. This page contains statistics about the bugs in MantisBT.

Bugnote

File Upload

MantisBT allows users to upload file attachements and associated them with bugs as well as projects. Bug attachments / project documents can be uploaded to the webserver, database, or an FTP server. When bugs are uploaded to the webserver they are uploaded to the path that is configured in the project properties.In case of problems getting the file upload feature to work, check the following resources: PHP Manual .

HTML

Authentication

Status Settings

See also: Customizing Status Values

Filters

Misc

Cookies

The configuration variables $g_string_cookie, $g_project_cookie, $g_view_all_cookie, $g_manage_cookie are calculated based on $g_cookie_prefix. When you change the cookie prefix in config_inc.php, you need to follow it with a copy of the four lines that calculate the names for these cookies.

Database Tables

MantisBT enables users to configure a table prefix for all its tables. This is useful to be able to have multiple MantisBT installation in the same database. The advantage of that is for users who are limited by their ISP to have one database.

Speed Optimisation

Reminders

Sending reminders is a feature where a user can notify / remind other users about a bug. In the past, only selected users like the managers, or developers would get notified about bugs. However, these people can not invite other people (through MantisBT) to look at or monitor these bugs.

This feature is useful if the Manager needs to get feedback from testers / requirements team about a certain bug. It avoid needing this person to do this manual outside MantisBT. It also records the history of such reminders.

Bug History

Bug history is a feature where MantisBT tracks all modifications that are made to bugs. These include everything starting from its creation, till it is closed. For each change, the bug history will record the time stamp, user who made the change, field that changed, old value, and new value.

Independent of the these settings, MantisBT will always track the changes to a bug and add them to its history.

Sponsorship

Source Control Integration

Custom Fields

My View Settings

Relationship Graphs

Sub-Projects

Field Visibility

System Logging

The system logging interface is used to extract detailed debugging information for the MantisBT system. It can also serve as an audit trail for user actions.

Time Tracking

MantisTouch

These options are used to integrate with MantisTouch (http://www.mantistouch.org) to provide experience targeted to mobile devices.

Login page

Just enter your username and password and hit the login button. There is also a Save Login checkbox to have the package remember that you are logged in between browser sessions. You will have to have cookies enabled to login.If the account doesn't exist, the account is disabled, or the password is incorrect then you will remain at the login page. An error message will be displayed.The administrator may allow users to sign up for their own accounts. If so, a link to Signup for your own account will be available.The administrator may also have annonymous login allowed. Annonymous users will be logged in under a common account.You will be allowed to select a project to work in after logging in. You can make a project your default selection from the Select Project screen or from your Account Options.SignupHere you can signup for a new account. You must supply a valid email address and select a unique username. Your randomly generated password will be emailed to your email account. If MantisBT is setup so that the email password is not to be emailed, newly generated accounts will have an empty password.

Main page

This is the first page you see upon logging in. It shows you the latest news updates for the bugtracker. This is a simple news module (based off of work by Scott Roberts) and is to keep users abreast of changes in the bugtracker or project. Some news postings are specific to projects and others are global across the entire bugtracker. This is set at the time of posting in the Edit News section.The number of news posts is controlled by a global variable. When the number of posts is more than the limit, a link to show "older news" is displayed at the bottom. Similarly a "newer news" is displayed when you have clicked on "older news".There is an Archives option at the bottom of the page to view all listings.ArchivesA title/date/poster listing of ALL past news articles will be listed here. Clicking on the link will bring up the specified article. This listing will also only display items that are either global or specific to the selected project.

View Issues page

Here we can view the issue listings. The page has a set of viewing filters at the top and the issues are listed below.FiltersThe filters control the behavior of the issues list. The filters are saved between browsing sessions but do not currently save sort order or direction.If the number of issues exceeds the "Show" count in the filter a set of navigation to go to "First", "Last", "Previous", "Next" and specific page numbers are added.The Search field will look for simple keyword matches in the summary, description, steps to reproduce, additional information, issue id, or issue text id fields. It does not search through issue notes. Issue List - The issues are listed in a table and the attributes are listed in the following order: priority, id, number of issue notes, category, severity, status, last updated, and summary. Each (except for number of issue notes) can be clicked on to sort by that column. Clicking again will reverse the direction of the sort. The default is to sort by last modification time, where the last modified issue appears at the top. The issue id is a link that leads to a more detailed report about the issue. You can also add issue notes here. The number in the issue note count column will be bold if an issue note has been added in the specified time frame. The addition of an issue note will make the issue note link of the issue appear in the unvisited state. The text in the "Severity" column will be bold if the severity is major, crash, or block and the issue not resolved. The text in the "Updated" column will be bold if the issue has changed in the last "Changed(hrs)" field which is specified in the viewing filters. Each table row is color coded according to the issue status. The colors can be customised through MantisBT Configuration .Severitiesblock - prevents further work/progress from being made crash - crashes the application or blocking, major - major issue, minor - minor issue, tweak - needs tweaking, text - error in the text, trivial - being nit picky, feature - requesting new feature - Status new - new issue, feedback - issue requires more information from reporter, acknowledged - issue has been looked at but not confirmed or assigned, confirmed - confirmed and reproducible (typically set by an Updater or other Developer), assigned - assigned to a Developer, resolved - issue should be fixed, waiting on confirmation of fix, closed - issue is closed, Moving the mouse over the status text will show the resolution as a title. This is rendered by some browsers as a bubble and in others as a status line text.

Issue View page

Here is the simple listing of the issue report. Most of the fields are self-explanatory. "Assigned To" will contain the developer assigned to handle the issue. Priority is fully functional but currently does nothing of importance. Duplicate ID is used when an issue is a duplicate of another. It links to the duplicate issue which allows users to read up on the original issue report. Below the issue report is a set of buttons that a user can select to work on the issue.

• Update Issue - brings up a page to edit all aspects of the issue

• Assign to - in conjunction with the dropdown list next top the button, this is a shortcut to change the assignment of an issue

• Change Status to - in conjunction with the dropdown list next top the button, this is a shortcut to change the status of an issue. Another page (Change Status) will be presented to allow the user to add notes or change relevant information

• Monitor / Unmonitor Issue - allows the user to monitor any additions to the issue by email

• Create Clone - create a copy of the current issue. This presents the user with a new issue reporting form with all of the information in the current issue filled in. Upon submission, a new issue, related to the current issue, will be created.

• Reopen Issue - Allows the user to re-open a resolved issue

• Move Issue - allows the user to move the issue to another project

• Delete Issue - Allows the user to delete the issue permanently. It is recommended against deleting issues unless the entry is frivolous. Instead issues should be set to resolved and an appropriate resolution category chosen.

A panel is provided to view and update the sponsorship of an issue.Another panel is provided to view, delete and add relationships for an issue. Issues can have a parent/child relationship, where the user is warned about resolving a parent issue before all of the children are resolved. A peer relationship is also possible.Below this, there may be a form for uploading file attachments. The Administrator needs to configure the bugtracker to handle file uploads. If uploading to disk is selected, each project needs to set its own upload path. Issue notes are shown at the bottom of the issue report. A panel to add issue notes is also shown.

Issue Change Status page

This page is used to change the status of an issue. A user can add an issue note to describe the reason for change.In addition, the following fields may be displayed for update:

• Resolution and Duplicate ID - for issues being resolved or closed

• Issue Handler (Assigned to)

• any Custom Fields that are to be visible on update or resolution

• Fixed in Version - for issues being resolved

• Close Immediately - to immediately close a resolved issue

Issue Edit page

The layout of this page resemples the Simple Issue View page, but here you can update various issue fields. The Reporter, Category, Severity, and Reproducibility fields are editable but shouldn't be unless there is a gross mis-categorization.Also modifiable are the Assigned To, Priority, Projection, ETA, Resolution, and Duplicate ID fields.As per version 0.18.0, the user can also add an issue note as part of an issue update.

My Account Page

This page changes user alterable parameters for the system. These selections are user specific.My AccountThis allows the user to change their password, screen name, and email address. It also reports the user's access levels on the current and other projects.

System Management Pages

A number of pages exist under the "Manage" link. These will only be visible to those who have an appropriate access level.

Monitor Issue

The monitor issues feature allows users to subscribe to certain issues and hence get copied on all notification emails that are sent for these issues.Depending on the configuration, sending a reminder to a user about an issue can add this issue to the user's list of monitored issues. Users who reported the issue or are assigned the issue typically don't need to monitor the issue to get the notifications. This is because by default they get notified on changes related to the issue anyway. However, administrators can change the configuration to disable notifications to reporters or handlers in specific scenarios.

Reopen Issue

Re-open issue button is visible in the issue view pages if the user has the appropriate access level and the issue is resolved/closed. Re-opening a issue will allow users to enter issue notes for the re-opening reason. The issue will automatically be put into the Feedback status.

Delete Issue

The delete issues button appears on the issue view pages for the users who have the appropriate access level. This allows you to delete an existing issue. This should only be used on frivolous or test issues. A confirmation screen will prompt you if you really want to delete the issue. Updaters, Developers, Managers, and Administrators can remove issues (you can also configure this).

Close Issue

This is a button that appears on the issue view pages for users that are authorized to close issues. Depending on the configuration, users may be able to close issues without having to resolve them first, or may be able to only close resolved issues. After the button is clicked, the user is redirected to a page where an issue note maybe added.

Assign to Me

This button appears in the issue view pages in case of users with access level that is equal to handle_bug_threshold or higher. When this button is clicked the issue is assigned to the user.

Resolve Issue

This option on the View Issues page allows you to resolve the issue. It will lead you to a page where you can set the resolution state and a duplicate id (if applicable). After choosing that the user can choose to enter an issue note detailing the reason for the closure. The issue is then set to the Resolved state. The reporter should check off on the issue by using the Close Issue button.

News Syndication

MantisBT supports news syndication using RSS v2.0 protocol. MantisBT also supports authenticated news feeds for private projects or installations where anonymous access is not enabled. Authenticated feeds takes a user name and a key token that are used to authenticate the user and generate the feed results in the context of the user's access rights (i.e. the same as what the user would see if they were to logged into MantisBT).To get access to the News RSS as anonymous user, visit the following page: http://www.example.com/mantisbt/news_rss.php While a user is logged in, the RSS links provided in the UI will always provide links to the authenticated feeds, if no user is logged in (i.e. anonymous), then anonymous links will be provided.

Custom Fields

---

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.

---

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

---

Defining Custom Dynamic Possible Values

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 adminstrator/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

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.

                    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';
            

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 ( lang_get_current() === 'english' ) {
                $s_access_levels_enum_string =
                '10:Betrachter,25:Reporter,40:Updater,55:Entwickler,60:Senior
                Developer,70:Manager,90:Administrator'; }
            

Email Notifications

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.

Customizing Status Values

This section describes how to add a custom status.

1. 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 );

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

3. 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( lang_get_current() ) {
   
   	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.';
   		;;
   
   	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.';
   }

4. 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';

Custom Functions

Custom functions are used to extend the functionality of MantisBT by integrating user writtenfunctions into the issue processing at strategic places. This allows the system administrator to changethe functionality without re-writing parts of the internals of the code.

User versions of these functions are placed in a file called custom_functions_inc.php in the root directory of MantisBT. This is the same place that the "config_inc.php" file modifying MantisBT defaults is placed. In normal processing, MantisBT will look for override functions and execute them instead of the provided default functions.

Custom functions have names like custom_function_override_descriptive_name where descriptive namedescribed the particular function. The specific functions are described below. The simplest way tocreate a custom function is to copy the default function, named custom_function_default_descriptive_namefrom the core/custom_function_api.php file to your override file (custom_functions_inc.php), andrename it. The specific functionality you need can then be coded into the override function.

<?php
# --------------------
# Hook to validate Validate field settings before resolving
# verify that the resolution is not set to OPEN
# verify that the fixed in version is set (if versions of the product exist)

function custom_function_override_issue_update_validate( $p_issue_id, $p_bug_data, $p_bugnote_text ) {
if ( $p_bug_data->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-&gt;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 );
}
}
}
?>
                    

                        define ( 'ERROR_VALIDATE_FAILURE', 2000 );
                        To custom_strings_inc.php
                        $MANTIS_ERROR['ERROR_VALIDATE_FAILURE'] = 'This change cannot be made because %s';
                    

Application Errors

Additional information about MantisBT common errors.

Standard Authentication

With Standard login method, MantisBT users are authenticated against records in the MantisBT database, where the passwords are stored as a hash.

Note: while technically unlimited, the password's length is arbitrarily restricted to 1024 characters (PASSWORD_MAX_SIZE_BEFORE_HASH constant).

Values for $g_login_method:

• MD5 is the default - and recommended - method

• Support for additional methods (e.g. SHA-1) could be added in the future

LDAP and Microsoft Active Directory

Value for $g_login_method: LDAP

Authentication is made against an LDAP or Active Directory server.

The LDAP parameters should be setup as explained in LDAP authentication parameters.

An MD5 hash of the user's password will be stored in the database upon successful login, allowing fall-back to Standard Authentication when the LDAP server is not available.

The user's ID and password is checked against the Directory; if the credentials are valid, then the user is allowed to login and their user account in MantisBT is created automatically.

Basic Authentication

Value for $g_login_method: BASIC_AUTH

When MantisBT is configured to use basic auth, it automatically detects the logged in user and checks if they are already registered in MantisBT, if not, then a new account is automatically created for the username.

The password length is limited to the size of the underlying database field (DB_FIELD_SIZE_PASSWORD constant), currently 32 characters.

HTTP Authentication

Value for $g_login_method: HTTP_AUTH

TODO

The password length is limited to the size of the underlying database field (DB_FIELD_SIZE_PASSWORD constant), currently 32 characters.

Deprecated authentication methods

The following methods of authentication are deprecated, and supported for backwards-compatibility reasons only. It is strongly recommended to update MantisBT installations relying on these to use standard authentication instead.

Deprecated values for $g_login_method:

• CRYPT

• CRYPT_FULL_SALT

• PLAIN

Change Log

MantisBT doesn't just track the status of issues, it also relates issues to versions. Each project can have several versions, which are marked with attributes like released and obsolete. Users typically report issues against released issues and developers typically fix issues in not released versions. With every new release comes question like: what's new? what has been fixed? Customers wonder if the new release is of interest to them and whether they should take an upgrade. Well, the change log is specifically tailored to answer these kind of questions.

In order for an issue to show up in the change log, it has to satisfy certain criteria. The criteria is that the issue has to be resolved with a 'fixed' resolution and has to have the 'fixed_in_version' field set. Users sometimes wonder why resolved or closed issues don't show up in the change log, and the answer is that the 'fixed_in_version' field is not set. Without the 'fixed_in_version', it is not possible for MantisBT to include the issues in the appropriate section of the changelog. Note that it is possible to set the 'fixed_in_version' for multiple issues using the 'Update Fixed in Version' group action on the View Issues page (just below the issues list). This option is only available when the selected project is not 'All Projects'. Once a version is marked as obsolete, it is now longer included in the change log.

MantisBT also provides the ability to customize the criteria used for an issue to be included in the change log. For example, for installations that use a custom set of resolutions, it is possible to select multiple resolutions as valid candidates for the change log. This can be done using custom functions (see custom functions documentation for more details). The custom function below overrides the MantisBT default behavior to include issues with both FIXED and IMPLEMENTED (a custom resolution) resolutions in the change log.

# --------------------
# Checks the provided bug and determines whether it should be included in the changelog
# or not.
# returns true: to include, false: to exclude.
function custom_function_override_changelog_include_issue( $p_issue_id ) {
    $t_issue = bug_get( $p_issue_id );

    return ( ( $t_issue->resolution == FIXED || $t_issue->resolution == IMPLEMENTED ) &&
        ( $t_issue->status >= config_get( 'bug_resolved_status_threshold' ) ) );
}

MantisBT also provides the ability to customize the details to include from the issue and in what format. This can be done using the following custom function.

# --------------------
# Prints one entry in the changelog.
function custom_function_override_changelog_print_issue( $p_issue_id, $p_issue_level = 0 ) {
    $t_bug = bug_get( $p_issue_id );

    if ( $t_bug->category_id ) {
        $t_category_name = category_get_name( $t_bug->category_id );
    } else {
        $t_category_name = '';
    }

    $t_category = is_blank( $t_category_name ) ? '' : '<b>[' . $t_category_name . ']</b> ';
    echo str_pad( '', $p_issue_level * 6, ' ' ), '- ', string_get_bug_view_link( $p_issue_id ), ': ', $t_category, string_display_line_links( $t_bug->summary );

    if ( $t_bug->handler_id != 0 ) {
        echo ' (', prepare_user_name( $t_bug->handler_id ), ')';
    }

    echo ' - ', get_enum_element( 'status', $t_bug->status ), '.<br />';
}

By combining both customization features, it is also possible to do more advanced customization scenarios. For example, users can add a 'ChangelogSummary' custom field and include all issues that have such field in the change log. Through customizing what information being included for a qualifying issue, users can also include the 'ChangelogSummary' text rather than the native summary field.

In some cases, users know that they fixed an issue and that the fix will be included in the next release, however, they don't know yet the name of the release. In such case, the recommended approach is to always have a version defined that corresponds to the next release, which is typicalled called 'Next Release'. Once the release is cut and has a concrete name, then 'Next Release' can be renamed to the appropriate name and a new 'Next Release' can then be created. For teams that manage releases from multiple branches for the same project, then more than one next release can be possible. For example, 'Next Dev Release' and 'Next Stable Release'.

Another common requirement is to be able to link to the change log of a specific project from the project's main website. There is a variety of ways to do that:

• To link to the changelog of version "ver1" of project "myproject":

  						http://www.example.com/mantisbt/changelog_page.php?project=myproject&version=ver1
  						

• To link to the changelog of all non-obsolete versions of project 'myproject':

  						http://www.example.com/mantisbt/changelog_page.php?project=myproject
  						

• To link to the changelog of project with id 1. The project id can be figured out by going to the management page for the project and getting the value of project_id field form the URL.

  						http://www.example.com/mantisbt/changelog_page.php?project_id=1
  						

• To link to the changelog of version with id 1. The version id is unique accross all projects and hence in this case it is not necessary to include the project id/name. The version id can be figured out by going to the manage project page and editing the required version. The version_id will be included in the URL.

  						http://www.example.com/mantisbt/changelog_page.php?version_id=1
  						

Another approach is to go to the project page and from there users can get to multiple other locations relating to the project include the change log. This can be done by a URL like the following:

http://www.example.com/mantisbt/project_page.php?project_id=1

It is possible to customize the access level required for viewing the change log page. This can be done using the $g_view_changelog_threshold configuration option.

Roadmap

One of the very important scenarios in project management is where the project managers (or team leads) triage the issues to set their priorities, target version, and possibly assign the issues to specific developers or take other actions on the issue. By setting the target version of an issue to a version that is not yet released, the issue shows up on the project roadmap, providing user with information about when to expect the issues to be resolved. The roadmap page has a section for each release showing information like planned issues, issues done and percentage of issues completed. Issues that are fixed in a specific version, but didn't have the target_version field set, will not show up in the roadmap. This allows the ability to control the issues that are significant enough to show in the roadmap, while all resolved fields can be found in the change log. Note that it is possible to set the 'target_version' for multiple issues using the 'Update Target Version' group action that is available through the View Issues page (below the issues list). This option is only available when the current project is not 'All Projects'. Although it is not a typical scenario, it is worth mentioning that once a version is marked as obsolete, it is not included in the roadmap.

Note that the roadmap only includes future versions, once a version is marked as released, it no longer is included in the roadmap. For information about such releases, the change log feature should be used. For an issue to be shown on the roadmap, it has to have the target version set. It does not matter whether the feature is resolved or not. Resolved features will be decorated with a strikethrough and will be counted as done.

MantisBT provides the ability to customize the criteria for issues to show up on the roadmap. The default criteria is that the issue has to belong to a version that is not yet released and that the issues is not a duplicate. However, such criteria can be customized by using custom functions as below.

# --------------------
# Checks the provided bug and determines whether it should be included in the roadmap or not.
# returns true: to include, false: to exclude.
function custom_function_override_roadmap_include_issue( $p_issue_id ) {
    return ( true );
}

It is also possible to customize the details included about an issues and the presentation of such details. This can be done through the following custom function:

# --------------------
# Prints one entry in the roadmap.
function custom_function_override_roadmap_print_issue( $p_issue_id, $p_issue_level = 0 ) {
    $t_bug = bug_get( $p_issue_id );

    if ( bug_is_resolved( $p_issue_id ) ) {
        $t_strike_start = '<strike>';
        $t_strike_end = '</strike>';
    } else {
        $t_strike_start = $t_strike_end = '';
    }

    if ( $t_bug->category_id ) {
        $t_category_name = category_get_name( $t_bug->category_id );
    } else {
        $t_category_name = '';
    }

    $t_category = is_blank( $t_category_name ) ? '' : '<b>[' . $t_category_name . ']</b> ';

    echo str_pad( '', $p_issue_level * 6, ' ' ), '- ', $t_strike_start, string_get_bug_view_link( $p_issue_id ), ': ', $t_category, string_display_line_links( $t_bug->summary );

    if ( $t_bug->handler_id != 0 ) {
        echo ' (', prepare_user_name( $t_bug->handler_id ), ')';
    }

    echo ' - ', get_enum_element( 'status', $t_bug->status ), $t_strike_end, '.<br />';
}

Some teams manage different branches for each of their projects (e.g. development and maintenance branches). As part of triaging the issue, they may decide that an issue should be targetted to multiple branches. Hence, frequently the request comes up to be able to target a single issue to multiple releases. The current MantisBT approach is that an issues represents an implementation or a fix for an issue on a specific branch. Since sometimes applying and verifying a fix to the two branches does not happen at the same time and in some cases the approach for fixing an issue is different based on the branch. Hence, the way to manage such scenario is to have the main issue for the initial fix and have related issues which capture the work relating to applying the fix to other branches. The issues for porting the fix can contain any discussions relating to progress, reflect the appropriate status and can go through the standard workflow process independent of the original issues.

Another common requirement is to be able to link to the roadmap of a specific project from the project's main website. There is a variety of ways to do that:

• To link to the roadmap of version "ver1" of project "myproject":

  						http://www.example.com/mantisbt/roadmap_page.php?project=myproject&version=ver1
  						

• To link to the roadmap of all non-obsolete versions of project 'myproject':

  						http://www.example.com/mantisbt/roadmap_page.php?project=myproject
  						

• To link to the roadmap of project with id 1. The project id can be figured out by going to the management page for the project and getting the value of project_id field form the URL.

  						http://www.example.com/mantisbt/roadmap_page.php?project_id=1
  						

• To link to the roadmap of version with id 1. The version id is unique accross all projects and hence in this case it is not necessary to include the project id/name. The version id can be figured out by going to the manage project page and editing the required version. The version_id will be included in the URL.

  						http://www.example.com/mantisbt/roadmap_page.php?version_id=1
  						

Another approach is to go to the project page and from there users can get to multiple other locations relating to the project include the roadmap. This can be done by a URL like the following:

http://www.example.com/mantisbt/project_page.php?project_id=1

The access level required to view and modify the roadmap can be configured through $g_roadmap_view_threshold and $g_roadmap_update_threshold respectively. Modifying the roadmap is the ability to set the target versions for issues. Users who have such access can set the target versions while reporting new issues or by updating existing issues.

Time Tracking

This is currently a work in progress. To follow the work have a look on the wiki page Time Tracking (Issue 4428)

To activate the Time Tracking feature you have to set the configuration option "time_tracking_enabled" to ON. To activating the Time Tracking you can :

• Static solution : change the variable '$g_time_tracking_enabled' in the configuration file 'config_defaults_inc.php', this will change the configuration for all the MantisBT instance ;

• Dynamic and "project by project" solution : Use the administration page "Manage Configuration" and set the variable 'time_tracking_enabled' to '1' for which user and which project of you choice.

All Time Tracking configuration options are described in the configuration section off this guide.

Graphs

Assigned to me: TODO

Release Delta: TODO

Category: TODO

Severity: TODO

Severity / Status: TODO

Daily Delta: TODO

Reported by Me: TODO

Summary Page

By Status: TODO

By Severity: TODO

By Category: TODO

Time Stats for Resolved Issues (days): TODO

Developer Status: TODO

Reporter by Resolution: TODO

Developer by Resolution: TODO

By Date: TODO

Most Active: TODO

Longest Open: TODO

By Resolution: TODO

By Priority: TODO

Reporter Status: TODO

Reporter Effectiveness: TODO

Talent and Time

One of the greatest ways to contribute to MantisBT is to contribute your talent and time. For MantisBT to keep growing we need such support in all areas related to the software development cycle. This includes: business analysts, developers, web designers, graphics designers, technical writers, globalization developers, translators, testers, super users, packagers and active users. If you would like to contribute in any of these capacities please contact us through the "Contact Us" page.

Recommend MantisBT to Others

It feels great when we get feedback from the user community about how MantisBT boosted their productivity, and benefited their organization. A lot of the feedback I get is via email, some on mailing lists, and some on forums. I would encourage such users to blog about it, tell their friends about MantisBT, and recommend MantisBT to other organizations. MantisBT is driven by it's community, the greater the community, the greater the ideas, the greater of a product it becomes.

Blog about MantisBT

If you have a blog, then blog about MantisBT, review it's features and help us spread the word. A lot of users also like to blog about how they customized MantisBT to fit their needs or to integrate with other tools that they use in their work environment.

Integrate with MantisBT

If you have a product that can be integrates with MantisBT to provide a value for MantisBT users, that would be a great place to contribute and benefit both your project's community and the MantisBT community. A great examples in this area are integrations with content management systems (e.g. *Nuke, Xoops), project management (PHPProjekt), and TestLink for Test Management. MantisBT can easily be integrated with projects in any programming language whether it is hosted on the same webserver or anywhere else in the world. This can be achieved through it's SOAP API and MantisConnect client libraries. MantisConnect comes with client libraries and samples in languages like PHP, .NET, Java and Cocoa.

Registered in MantisBT Users Directory

Join the Users Directory by clicking Submit. While entering your company or project details you will be able to write up a testimonial about MantisBT which will then be included in the Testimonials page.

Donate Money

Use the PayPal donate buttons that you will see around the website (e.g. bottom left of the home page). You can donate using your credit card even if you don't have a PayPal account. Donations is a very easy way for the MantisBT community to give back to MantisBT. The donations can be as small as US$1 or as big as you or your organization want it to be.

Sponsor MantisBT

MantisBT Sponsors are organizations that have realized the benefit brought to their business by using MantisBT and would like to protect such investment and always push it forward via sponsorship. Please take a moment to visit our sponsors page and use the "Contact Us" page for further information.