# Tracker

## What is the Tracker?

The Tracker is a generic system where you can store items like bugs, feature requests, patch submissions, etc.

You can use this system to track virtually any kind of data, with each tracker having separate user, group, category, and permission lists. You can also easily move items between trackers when needed.

Trackers are referred to as Artifact Types and individual pieces of data are Artifacts. Bugs might be an Artifact Type, while a bug report would be an Artifact. You can create as many Artifact Types as you want, but remember you need to set up categories, groups, and permission for each type, which can get time-consuming.

When a project is created, FusionForge creates automatically 4 trackers:

Bugs

  Used for Bug tracking

Support Requests

  Users can insert here support requests and receive support

Patches

  Developers can upload here patches to the software

Feature Requests

  Requests for enhancements of the software should be posted here

## Using a Tracker

The following descriptions can be applied to any of the trackers. The functionalities between the different trackers are the same, we'll use the Bugs Tracker as example to describe the functionality of all trackers.

The Tracker provides the following functions:

1. Submitting a new item

2. Browsing of Items

3. Downloading CSV file

4. Reporting

5. Monitoring

6. Administration

## Submitting a new Bug

To submit a new bug, click on the Submit New link. A form will be displayed, where you can insert/select the following data:

Assigned To

  You can assign the item to a user. Only users which are Technicians are listed here.

Priority

  You can select the Priority of the item. In the Browse list, and the homepage of the users, priorities are displayed in different colors, and can be ordered by priority.

Summary

  Give a short description of the bug, e.g. Logout function gives an SQL Error

Detailed Description

  Insert the most detailed description possible.

File upload

  You can also upload files as attachment to the bug. This can be used to attach a screenshot with the error and the log file of the application.

  To upload files, select files using the Browse button. You can upload up to 5 files at a time.

  Attachments to tracker items can be no larger than 256KB.

Some custom fields may have been added by administrators. Default bug trackers propose the following additional fields: Resolution, Severity, Version, Component, Operating System, Product, Hardware, URL.

When the user is not logged, he will still be proposed to submit new bugs. If the Tracker allows anonymous posting, he will be able to post without logging in. If the Tracker does not allow anonymous posting, clicking on the Submit New link will prompt the user with the login banner.

## Browse Bugs

The Browse page shows the list of bugs. You can create and save queries allowing filtering on any defined fields.

You can sort the items by ID, Summary, Open Date, Submitter and the Ordering (ascending, descending).

The different colors indicate the different priorities of the bug; a * near the open date indicates that the request is more than 30 days old. The overdue time (default 30 days) is configurable for each tracker.

When you click on the summary, you go to the detail/modify Bug page.

## Modify Bugs

In the modify Bug page, you can modify the data you inserted, and also add the following information:

Data Type

  This combo box lists the trackers of the project. If you select a different tracker and submit the changes, the item will be reassigned to the selected tracker.

Status

  The status indicates the status of the item. When an item is inserted, it is created in the Open state. When you fix a bug, you should change the state to Closed.

Canned Responses

  Canned responses are prefixed responses. You can create canned responses for your project in the admin section and select the responses in the combo box.

The Changelog on the bottom of the page shows in chronological order the changes applied to the item. Also all followups can be viewed.

## Monitor Bugs

You can choose to monitor a tracker as a whole, or only individual tracker entries.

### Monitoring an entire tracker

Go to the tracker page and select Monitor link.

To stop monitoring the tracker, select Stop Monitor link.

### Monitoring tracker entries

If you select the Monitor button on the top left of the Bug detail page, bug monitoring will be enabled.

When you are monitoring a bug, every change to the bug will be sent to you by email.

To disable bug monitoring, simply select the Stop Monitoring button.

## Admin Tracker

If you are an Administrator of the tracker, you can add or change bug groups, categories, canned responses:

Manage Custom Fields

  You can add new fields or change the name of ones.

  You can select the type of box (select box, check box, radio button, text field, multi-select box and status) and the possible values.

Add Update Canned Responses

  Canned responses are predefined responses. Creating useful generic messages can save you a lot of time when handling common requests.

Update preferences

  Here you can update the following information on the tracker:

  Name

    The name of the Tracker. This is the name displayed in the tracker list, e.g. Bug Submissions.

  Description

    The description of the Tracker. E.g. This is the tracker dedicated to the Bugs of the project

  Publicly Available

    By default, this checkbox is not enabled.

  Allow non-logged-in postings

    If this checkbox is enabled, also non logged-in users can post items to the tracker. If this checkbox is not enabled, only logged in users can post items.

    By default, this checkbox is not enabled.

  Send email on new submission to address

    All new items will be sent to the address inserted in the text box.

  Send email on all changes

    If this checkbox is enabled, all changes on the items will be sent out via email. It is useful to check this radiobutton only if in the Send email address is inserted an email address.

  Days still considered overdue

  Days till pending tracker items time out

  Free form text for the Submit new item page

    This allows you to put a specific introduction on the submit new item page.

  Free form text for the Browse items page

    This allows you to put a specific introduction on the Browse items page.

## Mass Update

If you are an Administrator of the tracker, you are also enabled for the Mass Update function.

This function is visible in the browse bug page and allows you to update the following information:

1. Priority

2. Assignee

3. Status

4. Canned Response

When this function is enabled, a checkbox will appear at the left side of each bug id. You can check one or more of the ids, select one or more of the values in the Mass Update combo boxes and click Mass Update.

All selected bugs will be modified with these new value(s). This function is very useful if you need to change the same information for more bugs; e.g. assigning 5 bugs to one developer or closing 10 bugs.

This function allow to update all selected box fields, not only mandatory fields but also custom fields.

## Reporting

The reporting functions allows to check the life-span of the Bug. The lifespan is the duration of the bug; it starts when the bug is inserted (opened) in the tracker and ends when the bug is closed.

- By assignee

- Response time

## Searching for bugs

When using a tracker, a voice with the name of the tracker will appear in the search combo box. The search will be done on the description, the summary, the username of the submitter and the username of the assignee.

Giving a number will redirect to the corresponding tracker id.

## Adding a comment to a tracker by e-mail

When a user receives an e-mail about a tracker, he can add add a comment to this tracker by replying to this e-mail.

The e-mail reply must use plain text format. An HTML e-mail will lead to an error message.

## Managing trackers via CLI (Command-Line Interface)

We give here some basic examples of CLI commands. For more information, please consult the FusionForge Command-line interface (CLI) documentation.

### Logging in with CLI

    gforge.php -v login --username="user" --project=myproject

### Getting the list of tracker entries via CLI

Use CLI to get the tracker id for a given project

    gforge.php tracker typelist

Use CLI to get the list all bugs for a given project

    gforge.php tracker list --type=xxx

### Creating a tracker entry via CLI

    gforge.php tracker add --type=xxx --priority=4 --summary="New bug"
                           --details="This is a brand new bug"

### Updating a tracker entry via CLI

    gforge.php tracker update --type=xxx --id=yyyy --priority=5
                       --summary="New summary" --details="New details"

You can include a Custom Field, e.g. Group

    gforge.php tracker update --type=xxx --id=yyyy --priority=5
                              --summary="New summary" --group=zzzz