This page in other versions: master
FusionForge provides a complete and powerful issue/bug/feature tracking system.
- 1 Main Features
- 2 Plugin extensions
- 3 Available Widgets
- 4 Activation
- 5 Trackers Main Page
- 6 Tracker
- 7 Browse Page
- 8 Import/Export
- 9 Reporting
- 10 Artifacts
- 10.1 Display view configuration
- 10.2 Submit New
- 10.3 Modify existing
- 11 Roadmap
- unlimited number of trackers. A tracker is a specific set of permission per role, a complete configuration of fields, workflow, etc. Each tracker can be set independently providing a large amount of freedom.
- unlimited number of artifacts. Each artifact has his unique id.
- role based access per tracker.
- workflow per tracker. Linking fields with role to define a full life cycle of the artifact.
- custom fields per tracker. To extend default fields of an artifact to enhance the experience and the use.
tracker system can be extended using the following plugins:
- Projects Hierarchy provides hierarchical 1:n view to list trackers
- scmhook provides hooks for linking artifact and commits
- taskboard to get Agile features
user oriented widgets
project oriented widgets
To enable this system at forge level, the configuration flag use_tracker must be set to yes. Per project, the system can be enable/disable through the Project admin page.
Trackers Main Page
The Project Trackers Main Page displays a submenu and a 4-column table listing each available tracker. Permissions apply, i.e. only accessible trackers to the user are displayed.
- View Trackers: point to the Trackers Main Page
- Roadmap: point to the roadmap feature.
- Reporting: some graphical reports on trackers usage.
- Administration: link to Administrative page to create new tracker and get direct access to the dedicated Administrative page of each tracker or to manage the roadmap feature.
The table has the following columns. Click on column title to reorder.
- Tracker Name
- Tracker Description
- Total of open artifacts
- Total of artifacts
Tracker creation requires:
- a name
- a description
- an unique email address to set any new artifact submission
- tick send email on all changes to receive notification on all modification/creation of artifacts in this tracker.
The following fields are not used but still displayed:
- Days till considered overdue
- Days till pending tracker items timeout
To create a new tracker, click on Administration tab from the Tracker Main page, fill the required fields and click on Submit. User requires Trackers Administration permission.
Relying on RBAC, tracker permissions are splitted into 2 groups.
- Trackers administration permissions:
- No administrative access: when set, then the per tracker permission apply.
- Trackers Administration: when set, then role has full access to any tracker and any action over tracker
- Per tracker permissions:
- No access: This setting forbids access to any artifacts of this tracker (tracker not visible in the browse page, no visibility in the project activity tab, ...).
- Read only: User can browse the tracker, see artifacts of this tracker in the project activity tab but cannot modify any element (no comment, no new artifact).
- Read & submit: User can browse and create new artifact but cannot modify existing artifacts.
- Tech & Manager
- Read & submit + Vote: same as Read & submit with vote permission.
- Technician + Vote: same as Technician with vote permission.
- Manager + Vote: same as Manager with vote permission.
- Tech & Manager + Vote: same as Tech & Manager with vote permission.
The section Default for new tracker applies when new tracker is created.
Once a tracker is created and permissions set, it is possible to adjust the configuration to fit specific usage.
Once tracker created, user can modify the following elements:
- name of the tracker
- description of the tracker
- unique email address used to send notification on creation
- check/uncheck send notice on all changes
- days till considered overdue (not used)
- days till pending tracker items time out (not used)
- free form text for the “Submit New” page
- free form text for the Browse page
Click on Submit to validate modification.
notice: in some case, on old FusionForge installation, name and description cannot be modified.
This feature is to track time spent on artifact. Time value can be anything but should be meaningful such as hour, day, week. Time values are inherited by default by the parent definition. Tracker inherits from project. Project inherits from the Forge itself. At each level, user can redefine the values, i.e: a tracker can have his own definition of a day. For instance, a day can be 7 hours of work only. Effort units are used as reference values in the Effort custom field.
Each tracker comes with default fields and can be enhanced with custom fields which may overwrite default fields. Each field have properties (name and values are the obvious one). Each artifact is defined by value of each field.
- Id: automatically generated. Incremented.
- Summary: manual entry
- Description: manual entry
- Submitted by: automatically set on artifact creation
- Open date (Date Submitted): automatically set on artifact creation
- Last modified date: automatically set on artifact modification
- Last modified by: automatically set on artifact modification
- Closed date: automatically set on artifact modification
- Data Type: manual entry. Data Type is the tracker.
- State: manual entry. By default, State is set to open on artifact creation. This field comes with 2 values by default: open or close. The custom field Status overwrites this field.
- Priority: manual entry. From 1 to 5, where 1 is the lowest to 5 the highest priority.
As a complement to the default fields, each tracker can enhanced by creating & setting custom fields. There are 3 kinds of custom fields:
- generic: checkbox, radio buttons, selectbox, multiselectbox, textfield
- project specific: users, file release, efforts
- overwrite default fields: status
No limits of number of custom fields per tracker. More information about custom fields on dedicated page.
Per tracker, a status workflow can be created. It requires to set a custom field status. Workflow aims to allow/forbid move from one status to another to roles and required fields to be set.
Only one workflow can be created per tracker. More information about workflow on dedicated page.
This feature offers the ability to define messages to be select as comment on artifact modification.
To administrate canned responses, user must have manager permissions on the tracker. Existing canned responses can be deleted. A canned response requires a title and a body.
From the mass-action block, canned responses can be apply as comment to all selected artifacts. For a specific artifact, from the modification view, canned responses are available at the Comments level. Once canned responses selected, the message appears in the Post comment: text area and can be modified.
Browse custom list
By default, the following fields are displayed:
- Open Date
- Assigned to
- Submitted by
This list can be modified in the Administration Menu > Customize List entry. The field list can be reordered. New field can be added, based on existing default fields and custom fields. Field can be also removed from the list using the delete action.
The Id field cannot be removed. This field is mandatory to get Mass Update action.
When a project is defined as template, any template of this project can be used as template in other project. A template tracker is used to setup quickly a tracker with the same settings as the template tracker:
- canned responses
- effort units
- widget layout if forge is using the artifact widget display.
The delete action is definitive. It cannot be undone. To delete a tracker, user must have manager permission on this tracker. The deletion must be confirm by user. The deletion removes all element (configuration, artifacts, attachments, ...) of this tracker.
To delete a tracker:
- select the tracker
- enter the Administration submenu
- click on Delete entry
- confirm and click on the Delete button.
The browse page is organized into 4 areas and a main listing resulting of filtering. The 4 areas are:
- the dynamic submenu (1)
- the paging preference access (2)
- the Query builder block (3)
- the Mass Update block (4)
The main listing displays the column as selected in configuration of the tracker (See how to customize this list). The number of artifacts is according the paging preference and/or the max. number of artifacts found.
The submenu is dynamic depending on the action user is doing and user permissions. On the browsing page, the submenu contains the following elements:
- View Trackers: point to entry page of the tracking system of the project
- <name of the tracker>: point to the browse page itself
- Export CSV: point to Export page.
- Submit New: point to the artifact creation page. Requires submit permission to get this submenu entry.
- Reporting: point to the reporting/statistic page. Requires to have manager permission.
- Monitor: enable/disable monitoring this tracker. Requires to be logged and having read permission.
- Administration: point to administration page. Requires Administrative permissions.
Only available if user is logged.
The paging preference can be modify on this page to select the number of artifacts displayed. This preference is unique per user across the forge. Default value is 25. Modifying here the paging preference will modify it to all pages using the paging system such as document browse page.
Two kind of queries are available:
- Advanced query: using the powerful Query builder to create specific query to apply on filtering.
- Simple filtering and sorting: where user can select ordering or filtering artifact list.
See Query builder page for more information.
By default, the Mass Update block is collapsed. To open the block, click on the small arrow on top left of the border.
Ticked artifacts can be massed updated. Only select or multiselect type of custom fields can be mass-updated.
To export as CSV a tracker, user must have read access to the tracker. This export is per tracker. Exported default field elements are (one line per artifact):
The custom fields are exported as well.
This export does not include attachments to artifacts.
To export a tracker, select the tracker to browse, click on Export as CSV entry submenu. Adjust the separator and header if needed, use advanced options if needed. Click on Download as CSV button.
Separator & Header
User can adjust the separator to use (default is comma) and include a header. This header is the list of column name.
By default, the Advanced Options block is collapsed. To open the block, click on the small arrow on top left of the border.
The browsing page default filter is applied on CSV export. To overwrite this setting, user can open the Advanced Options and tick the overwrite default filtering.
Exported data can be limited by using the From advanced option to set a date to export the data from this date to now.
The XML export is available at <forge_fqdn>/export/tracker.php. It requires read permission on the tracker.
It requires 2 parameters to get the XML export output:
- group_id: where group_id is the ID of the project to export
- atid: where atid is the ID of the tracker to export
<forge_fqdn>/export/tracker.php?group_id=25&atid=123 will return (if user has read access) the XML output of the tracker id 123 of the project id 25.
This RSS feed presents the following information:
- A title with a linked icon to jump to the Project Tracker Main Page.
- per tracker:
- title to jump to Tracker Browse Page
- description of the tracker with the total of open & closed issues.
The permission settings apply, i.e: user must have read permission to list trackers.
Forge command line
The forge binary located in the ~/bin/ directory. It provides functions to import/export artifact, tracker.
More information about forge command line here
To have access to reports, user must have manager permission. FusionForge provides 2 reports:
- distribution across assignee through time
This report displays the percentage of artifacts by assignee per tracker between start month and end month.
The select menu Type has no action on this report.
- response time through time.
Display view configuration
There is 2 options to configure the view of an artifact.
- Use the default 2-columns view with an advanded PHP/html template mechanism
- Use the widget system to organize the elements in the artifact page.
The default view is organized into 3 parts:
- at top, 2 hardcoded columns. The internal fields are displayed on top of the 2 columns, then the customfields are added below the internal fields.
- the middle of the page contents the title and the description of the artifact
- at bottom, the follow-up tabs are displayed.
Custom Field Rendering Template
The default 2-columns table can be modify to reorder the custom fields. It requires HTML skills. Only reordering of custom fields is possible. The 2-columns view cannot be modified. Once modified, to reset the default 2-columns, the delete template link must be used.
Artifact Tracker Widget View
This view reuses the Widget System available for Forge, Project and User homepage. It provides the ability to organize the display per tracker. By default, the following widgets are activated and cannot be disabled or minimzed:
To enable this view, the configuration flag use_tracker_widget_display must be set to yes. This setting is forge-wide.
User requires to have at least read & submit permission on the targeted tracker to submit a new artifact in a tracker.
To create an artifact, follow the next actions:
- select the tracker
- click on Submit new submenu entry
- fill the form
- set the summary of the artifact (mandatory)
- set the detailed description of the artifact (mandatory)
- select values for each required fields and adjust if needed the other field
- attach any files if needed to the artifact. Up to 5 files can be attach on submission. The maximum size of attachments is based on the PHP configuration.
- click on Submit button.
The default fields Priority & Assigned To require Manager permissions. Once submitted, user is redirected to the listing page of artifacts in the tracker.
Text Format in Description, Comment
The text format of the detailed description or of a comment can include reference to other Fusionforge objects such as document, artifact, forum message, task as long as these objects belong to the same project. To do so, users can use the following syntax:
- [#xxx] refers to an artifact where xxx is the id of an artifact
- [Dxxx] refers to a document where xxx is the id of a document
- [Txxx] refers to a task where xxx is the id of a task
- [forum:xxx] refers to a forum message where xxx is the id of a forum message
- [wiki:xxx] refers to a wiki page where xxx is the name of the page
Using the configuration flag tracker_parser_type set to markdown allow users to use markdown syntax in detailed description or in comment of an artifact.
To modify an artifact, select the artifact using the search engine or the browse page for instance. Each artifact has an unique permanent link across the FusionForge instance. The link format is: <forge_fqdn>/tracker/a_follow.php/<xyz> where xyz is the ID of the artifact.
Modify title & description
User must have manager permission to modify initial title & description of existing artifact. To modify them, user has to click on the edit icon, then the title & description fields turn into editable text zones.
- Delete an artifact: the internal flag of the artifact is set to deleted. The artifact is not displayed in any query or search. Action available for user with technician permission.
- Monitor an artifact: to monitor an artifact, this requires to be logged in. Anonymous user cannot monitor an artifact.
- Vote: Requires vote permission.
- Data Type: Display the name of the tracker the artifact is part of. User with manager permission can move the artifact from the current tracker to another one if any other tracker in the same project exists.
- Priority: From 1 (lowest) to 5 (highest), help to order artifacts and build priority. User with manager permission can modify priority of an artifact.
- Assigned To: Select the user to assign the artifact to. User must have manager permission to set assignment.
- State: Current status of the artifact. User with technician permission can modify status of an artifact. The available status by default are: open, close. These 2 default status can be overwritten using the custom field Status.
- Submitted By: Display name of the User that submitted the artifact.
- Date Submitted: Date of the submittion of the artifact
- Last Modified By: Display name of the last user who has modified the artifact.
- Last Modified: Date of last modification of the artifact.
- Permalink: Provide the permalink URL of the artifact. The URL format is: <forge_fqdn>/tracker/a_follow.php/<xyz> where xyz is the ID of the artifact.
The follow-up tabs is a complete set of tabs displaying specific information. Some tabs are displayed if the feature is activated by the project or the FusionForge installation: i.e: Related Tasks is available only if the project is using the Project Management tool.
Post a comment
This tab displays all comments already posted to this artifact. Each post included the name of the submitter. Comments can be ordered by time of creation (up/down). The ordering is an user preference.
User can post a new comment to an artifact. User with technician permission can used canned response to prepare and post the comment.
Add an attachment
Users can attach files to an artifact. There is no limit number of attachment to an artifact. An attachment is not related to a comment. An attached file can be removed. Upload size limit applies.
Associate to another Fusionforge object
History of an artifact
- Related Tasks
- Commits: An artifact can be referenced into a commit message. See SCM Hook Plugin for more information. Once setup, the commit message must include the reference to the artifact as [#xyz] where xyz is the ID of the artifact. This tab list the different commits referring the artifact, including direct link to the commit.