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

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, macOS and a variety of Unix operating systems.

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

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.

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

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.

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.

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

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

Our release numbering convention follows the guidelines of Semantic Versioning. Given a version number Major.Minor.Patch and an optional Suffix (eg. 1.3.0-rc.1):

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

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

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

Start by checking Section 2.2, “System Requirements” and installing the appropriate version of required software.

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

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

The installation procedure will go through the following steps:

This chapter explains how to upgrade an existing MantisBT installation.

Start by Performing the steps described in Section 2.3, “Pre-installation / upgrade tasks” above.

There are many settings that you can adjust to configure and customize MantisBT. Refer to Chapter 5, Configuration, as well as the config_defaults_inc.php file for in depth explanations of the available options. Check out also Chapter 7, Customizing MantisBT 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 subfolder config 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.

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

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

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

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.

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

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

It is recommended that you make a backup in case you wish to use your data in the future. See Section 2.10, “Backups” for details.

To uninstall MantisBT: If you have the permissions to create/drop databases and you have a specific database for MantisBT that does not contain any other data, you can drop the whole database.

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:

Creating a user triggers the following actions:

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.

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:

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.

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

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 user signup is enabled, then it is required that $g_send_reset_password is ON as well, and the e-mail settings properly configured (see Section 5.8, “Email”).

If email notifications ($g_enable_email_notification) is set to ON, users with access level of $g_notify_new_user_created_threshold_min and above 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.

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

Administrators are able to impersonate users in order to reproduce an issue reported by a user, test their access making sure they can access the expected projects/issues/fields, or to create API tokens for service accounts that are used to grant other systems limited access to MantisBT.

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.

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 particularly 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", "Users", and clicking the "Prune Accounts" button inside the "Never Logged In" box.

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 overridden 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 define what access level can perform the operation. For example, adding a note may require REPORTER access level, updating it note may require DEVELOPER access level, unless the note was added by the same user.

Such threshold configuration options can be set to a single access level, which means users with such threshold and above are authorized to perform the action. The other option is to specify an array of access levels which indicates that users with the explicitly specific thresholds are allowed to execute the 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.

If you are using a global user directory (LDAP, Active Directory), you may want to configure MantisBT so users who already exists in the directory will 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 option could be if 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.

Users can fine tune the way MantisBT interacts with them by modifying their user preferences to override the defaults set by the administrator; If the administrator changes a default setting, it will not automatically cascade in the users' preferences once they have been set, so it is the users' responsibility to manage their own preferences.

The user preferences include the following:

A user profile describes an environment that used to run the software for which issues are being tracked.

When reporting issues, users can elect to enter information like platform, operating system and version manually, or they can choose from a list of available profiles.

Each user has access to all the personal profiles they create, in addition to global ones; Profile data includes "Platform", "Operating System", "OS Version", and "Additional Description".

Global profiles are typically used by the administrator to define a set of standard system settings used in their environment, which saves users the trouble of having to define them individually. The access level required to manage global profiles is configured by the $g_manage_global_profile_threshold configuration option and defaults to MANAGER.

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

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.

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 (see Section 7.5, “Customizing Status Values”).

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

MantisBT is highly customizable through the web interface and configuration files. Configuration options can be set globally as well as customized for a specific project or user (except for options listed in $g_global_settings, see Section 5.5, “Configuration Settings”).

Configuration options can be set in config_inc.php and in the database (using the various manage pages). Values stored in the database take precedence over values defined in config_inc.php. The former can also be viewed and updated on the Configuration Report page (Manage > Configuration > Configuration Report).

To determine which value to use, MantisBT follows the list below, sequentially searching for the specified configuration option until a match is found.

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.

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

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

These variables control how the date is displayed. The default is ISO 8601 formatting.

Please refer to the PHP manual for details on available formatting options.

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

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: Section 7.4, “Email Notifications”

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

MantisBT allows users to upload file attachments and associate them with bugs as well as projects. Bug attachments / project documents can be uploaded to the webserver or database. 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 .

See also: Section 7.5, “Customizing Status Values”

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

In this context, MantisBT records individual changes to text fields (Description, Steps to Reproduce, Additional Information as well as Bug Notes). These revisions are controlled by the following settings.

MantisBT can display a graphical representation of the relationships between issues. Two types of interactive visualizations are available, dependencies and a full relationships graph.

This section describes settings which can be used to troubleshoot MantisBT operations as well as assist during development.

MantisBT exposes a webservice API which allows remote clients to interact with MantisBT and perform many of the usual tasks, such as reporting issues, running filtered searches and retrieving attachments.

The SOAP API is enabled by default and available at /api/soap/mantisconnect.php below the MantisBT root. A WSDL file which describes the web service is available at /api/soap/mantisconnect.php?wsdl below the MantisBT root.

The REST API is enabled by default. A Swagger sandbox and documentation for REST API is available at /api/rest/swagger/ below the MantisBT root.

The following options are used to control the behaviour of the MantisBT SOAP API:

By default, all issues are visible to any user within a project. To limit the visibility of issues there are several mechanisms.

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 anonymous login allowed. Anonymous 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.

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.

Here we can view the issue listings. The page has a set of viewing filters at the top and the issues are listed below.

The 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 pages (see Chapter 5, Configuration for details). Severities block - 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.

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.

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.

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:

The layout of this page resembles 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.

The user can also add an issue note as part of an issue update.

This page changes user alterable parameters for the system. These selections are user specific. This allows the user to change their password, username, real name and email address. It also reports the user's access levels on the current project and default access level used for public projects.

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

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.

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.

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

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.

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.

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.

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 username 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 https://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.

All the strings used in MantisBT including error messages, as well as those defined in plugins, can be customized or translated differently. This is achieved by overriding them in the Custom Strings File (config/custom_strings_inc.php), which is automatically detected and included by MantisBT code.

Defining custom strings in this file provides a simple upgrade path, and avoids having to re-apply changes to modified core language files when upgrading MantisBT to the next release.

<?php
$s_CODE = STRING;
$MANTIS_ERROR[ERROR_NUMBER] = STRING;

<?php
if( db_is_connected() ) {
	if( helper_get_current_project() == 1 ) {
		$s_summary = 'Title';
	}
}

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.

$g_access_levels_enum_string =
	'10:viewer,25:reporter,40:updater,55:developer,70:manager,90:administrator';

The Language Files (e.g. lang/strings_german.txt) provide the localised strings (German in this case) for enumerations. But again, the master list is the enumeration in the configs themselves, 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 config/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/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;

Update custom_strings_inc.php (see Section 7.1, “Strings / Translations”)

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

See Section 5.8, “Email” in the Configuration section.

Examples:

This section describes how to add a custom status.

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 Section 7.6.1, “Default Custom Functions” 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 config directory. 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.

<?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_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_VALIDATE_FAILURE, ERROR );
		}
	}
}

?>

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:

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 Section 5.21.2, “LDAP authentication method 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.

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.

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.

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 Section 8.1, “Standard Authentication” instead.

Deprecated values for $g_login_method: With CRYPT-based methods, the password's length is limited as per Standard Authentication. With PLAIN, its size is restricted as for Basic Authentication.

Additional information about common MantisBT errors.

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.

​<?php
​# --------------------
​# 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.

​
​<?php
​# --------------------
​# 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 ) ? '' : '&lt;b&gt;[' . $t_category_name . ']&lt;/b&gt; ';
​    echo str_pad( '', $p_issue_level * 6, '&#160;' ), '- ', 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 ), '.&lt;br /&gt;';
​}

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 typically 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:

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.

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.

​
​<?php
​# --------------------
​# 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:

​
​<?php
​# --------------------
​# 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 = '&lt;strike&gt;';
​        $t_strike_end = '&lt;/strike&gt;';
​    } 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 ) ? '' : '&lt;b&gt;[' . $t_category_name . ']&lt;/b&gt; ';
​
​    echo str_pad( '', $p_issue_level * 6, '&#160;' ), '- ', $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, '.&lt;br /&gt;';
​}

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 targeted 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:

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.

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 :

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

Assigned to me: TODO

Release Delta: TODO

Category: TODO

Severity: TODO

Severity / Status: TODO

Daily Delta: TODO

Reported by Me: TODO

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

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.

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.

If you have a blog, then talk 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.

If you have a product that can be integrated with MantisBT to provide value for MantisBT users, that would be a great place to contribute and benefit both your project's and the MantisBT community.

A great example 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 its SOAP API and MantisConnect client libraries. MantisConnect comes with client libraries and samples in languages like PHP, .NET, Java and Cocoa.