This article is part of Managing bug report in issue tracker series.

See managing bug reports in issue tracker for common information. Please, read it first. For common information and setup of Mantis itself - please see this article. The text below assumes that you already completed Mantis installation.

Below are detailed steps for recommended Mantis setup for automatic bug report submission. Before going through setup - make sure to upgrade your Mantis to the latest version (or at least 1.2.7) - there are some important bugs fixed.

Some steps below are optional, some steps must be executed only once (like custom fields creation), other are executed from time to time (like creating new projects for your new products) and the rest are executed regularly (like creating product versions).

Full list of necessary actions contains:

Please note that all actions below are just examples. It's recommendation, but it's not necessary to be absolutely like that. You may use another configuration.

Creating custom fields

1. (Manage/Manage Custom Fields) Create custom field to improve usefulness of EurekaLog. Most important field is "Count" - to store number of sent/occurred problems. Its type should be "Numeric" (integer); field name can be arbitrary, like "Occurrences", "Bug count", "Popularity", "Incidents", "Hit Count", etc. Other suggested custom fields are: "BugID" (to store BugID and search issues) and "e-mail" ("user e-mail", which is typically entered in MS Classic error dialog). "BugID" field should be text field ("String"), "e-mail" field should be either "String" type or "E-mail" type. Again, field names can be anything.

We strongly recommend to create at least "Count" and "BugID" fields.

Example: three new custom fields

Suggested setup for "Count" field

Suggested setup for "BugID" field

Suggested setup for "e-mail" field

2. Create any other additional fields as you need/like (you can submit values for custom fields at run-time via OnCustomWebFieldsRequest event).

Creating user accounts

1. (Manage/Manage Users) Create new non-admin user account for bug report submission. Make it "updater" or "reporter" level. "Reporter" level can only report about new bugs (create new bug reports). "Updater" level can alter existing bug reports - for example, updating "Count" field (see above). You may want to create additional accounts for each of your products - for increased security. Use your e-mail to setup initial password. Once password is set, you can set e-mail to any value.

Creating new user

Setting new password for the user

2. Once password is set - log off and log in as this user. Go to "My account" / "Preferences" and clear e-mail notifications, set default project, switch language to "English", and time zone to "UTC":

Setting properties of submitter account

3. (Optional, but strongly recommended; only for latest Mantis versions) Go to "My account" / "API Tokens" and create new API token:

Creating new API token for bug reporter account

New API token was created

Once API token was created - select it and copy to buffer. You will need to enter it into EurekaLog settings later.

You may create additional tokens.

4. Now, log off and log in again as administrator. Go to managing user and turn on "protected" checkbox for this user account (which means that user will not be able to change password); turn off "Notify user".

Make bug reporting account "protected"

Additionally, you may change e-mail field to dummy e-mail address.

[Optionally] And assign user to project (you may need to make this step after project was created - see below).

Assigning user to project

Repeat these steps for each bug submitter user account which you've created.

Note: Mantis also support anonymous logins. See also. Anonymous user is predefined user with "anonymous" or "guest" name and without the password. However, since Mantis supports protected users (which can't alters their account settings), anonymous posting is not recommended.

Creating projects

1. (Manage/Manage Projects) Create project for your product. You may create it as private (thus, it won't be visible to users except those who are explicitly assigned for it). You may also create several projects - one for each of your products. In this case you may want to create them as sub-projects of common master project. You can use master project to setup versions/category/etc and copy these settings to sub-projects. Be sure to assign reporter user account as "reporter" or "updater".

Creating new project for bug reports

2. Create category for the projects. If you don't need category - create something like "Auto-report" category. If you already have category - assign it. If you have master-project - you can copy categories from it.

3. Create versions for the project. If you don't use versioning (highly unrecommended) - you can skip this step. If you have master-project - you can copy versions from it.

You should create new version for each release of your software. I.e. when you release (publish on site, send to custom, etc) "YourSoftware 1.0.0.0" - you need to create "1.0.0.0" version. When you release update: "YourSoftware 1.0.1.0" - you need to add "1.0.1.0" version.

Version strings can be arbitrary like "1", "1.0", "1.0.1", "1.0.1.0" or even "1.0.1.0 beta 3". However, it's recommended to use four-number versions with optional textual description, for example: "1.0.1.0" and "1.0.1.0 beta 3".

Note: if you don't want to edit project each time you release new version - you can create versions for the future use. I.e. when you release "YourSoftware 1.0.0.0" - you can create "1.0.0.0", "1.0.1.0", "1.0.2.0", "1.0.3.0"..."1.0.10.0" versions.

For example:

Batch-creating versions for future use

When reporting - version are taken from file's version information, so you must supply the corresponding version in description of your .exe or .dll files.

Note: if file's version information doesn't match created project versions - EurekaLog will try to use closest match. If there is nothing similar - field will be empty.

Version can be marked as "released". You should do this for all released versions of your software. Marking version as "Released" will lead to its appearance in "Product Version" field. In other words, all versions are always shown in "Target Version" field. Only released versions are shown in "Product Version" field. If you create many versions, but don't mark them as "Released" - then "Product Version" field will be empty.

Important Note: EurekaLog will only for "Released" versions, if a corresponding option is enabled. Be sure to mark versions of your compiled .exe as "Released" in Mantis.

4. [Optional] (Manage/Manage Configuration/Workflow Thresholds, per-project) Setup project access rights - limit actions to minimum for "reporter" and "updater" levels:

Changing rights configuration

5. [Optional] (Manage/Manage Configuration/Manage Columns, per-project/per-user) Setup columns for better information view:

Adding custom fields to columns

Example of customized columns in "View issues"

This example above uses the following column list (custom fields are taken from example of custom fields above):

selection, edit, priority, custom_Count, id, custom_BugID, bugnotes_count, severity, status, ...

Most important field is "Count" (if you've created it) - sorting by "Count" will show you "bugs TOP 5", i.e. most popular bugs should be fixed first.

EurekaLog setup

1. Enter Mantis details into EurekaLog settings of your projects:

Mantis settings filled into EurekaLog options

Important Note: we recommend to use API tokens when possible. Please note, that you have to enter your login (username) even if you are using API token. In any way, always use your username as login, do not use your e-mail.

2. Set any additional/common send options.

3. Set/fill custom fields. EurekaLog has support for automatic managing of "Count", "BugID", "E-Mail" fields. You just need to enter field names in EurekaLog options. For other custom fields you need to fill them manually, for example:

uses

  EEvents, ESysInfo;

procedure SetCustomFields(const ACustom: Pointer; AExceptionInfo: TEurekaExceptionInfo; 

  ASender: TObject; AWebFields: TStrings; var ACallNextHandler: Boolean);

begin

  AWebFields.Values['License'] := GetYourApplicationLicense;

end;

initialization

  RegisterEventCustomWebFieldsRequest(nil, SetCustomFields);

end.

4. Add any custom data, additional attached files, write necessary event handlers, set exception filters, etc, etc.

Testing

1. Test sending. You can do this right in the EurekaLog send options dialog - by clicking on "Test..." button. This will send test bug report.

Suggested actions are:

These actions should test that sending is actually working.

2. Now it's time to test your application-specific sending.

Now your application is ready for deployment.

Maintaining projects

1. You need to create or update project versions when you ship new release of your software. If you've created a batch of versions in Mantis for future use - you may skip it until you've run out of versions.

See also: