The issue tracker can be configured by an administrator to suit a wide variety of workflow applications. Multiple issue trackers can be defined in the same folder; their settings can be unique or shared from a common definition.

Set Up an Issue Tracker

  • To use an issue tracker, your folder must have the Issues module enabled. It is enabled by default in many folder types, but if you do not see the necessary web parts, select (Admin) > Folder > Management > Folder Type, check the box for the Issues module, and click Update Folder.
  • Navigate to, or create, an Issue Definitions web part in the desired location.
  • Click Insert New and enter the name to use for your issue tracker.
  • Select the Kind of issue tracker you are creating (default is "General Issue Tracker").
  • Click Submit. If an issue tracker with the same name exists in the current folder, project, or "Shared" project (searched in that order), your new tracker will share the same definition. You'll be asked to confirm before the tracker is created.
  • Make any customizations necessary on the Issues Admin Page. These changes will apply to all trackers created using this named definition.
  • Click Save.
  • Click the name of the new tracker to open it.

To create multiple issue trackers in the same folder, create additional issue definitions. When you create a new Issues List web part, you will select which issue list to display from a drop down menu.

Configuration Options

[ Video Overview: Improved Issues List Customization ]

To customize the issue tracker, click the Admin button on the issues list grid border.

The issues admin page looks like this:

After making any changes as described below, click Save at the top of the page.


The Singular item name and Plural item name fields control the display name for an "issue" across the Issues module. For example, you might instead refer to issues as "Bugs", "Tickets", or "Opportunities" instead of "Issues".

Comment Display Order

By default, comments on an issue are shown in the order they are added, oldest first. Change the Comment Sort Direction to newest first if you prefer.

Populating the "Assign To" Dropdown

You can control the list of users that populates the Assigned To dropdown field. By default, the drop-down shows "All Project Users":

This displays all users who are:

Administrators are not included when "All Project Users" is selected, unless they are explicitly added to some project-level security group.

You can populate the dropdown from an individual security group using the Specific Group drop-down. Both site-level and project-level security groups are available.

To be displayed in the "Assigned To" dropdown, group members must be assigned the Editor role or higher in the given folder.

In some workflows it is useful to have a default user to whom all issues are assigned, such as for initial triage and balancing assignments across a group.

Customize Fields

The issue tracker includes a set of commonly used fields by default, and you can use the field properties customizer to add additional fields and modify as needed to suit any application. Fields can be reordered, and any field showing an "X" is not required by the system and may be deleted. Customize labels and define field types, use lookups and validation to simplify user entry and data consistency.

When you make a field a lookup, shown here in the case of the "Resolution" property, the user updating an issue will be shown a picklist of items on the list given, here "mynewtracker-resolution-lookup"

Required Fields

You can specify that a field must have a value before a new issue can be submitted by checking the Required box on the Validators tab. When a user creates or edits an issue, required fields are marked with an asterisk (*).

Default Values

To set a default value for a field, highlight the field and select the Advanced Tab. The default can be fixed, editable, or based on the last value entered. Click Set Value to set the default value. All fields with default values enabled may be edited simultaneously:

Protect Fields

To require that a user have insert (editor) or higher permissions in order to see a given field, use the Protected checkbox on the Advanced tab. Anything without that box checked can be viewed by anyone with read permissions.

Selection Lists

If you want a list to offer the user a "pick list" of options, you will populate a list with the desired values and add a field with the type Lookup into the appropriate list. Built in fields that use selection options (or pick lists) include:
  • Type: the type of issue or task
  • Area: the area or category under which this issue falls
  • Priority: the importance of this issue
  • Milestone: the targeted deadline for resolving this issue, such as a release version
  • Resolution: ways in which an issue can be resolved, such as 'fixed' or 'not reproducible'
The list of options for each field is named combining the issue tracker name and field name. For example, in an issue tracker named "My Project Issues", the selection list for the "Type" field is named Lists.myprojectissues-type-lookup and looks like this by default:

When a user is entering a new issue, the pulldown for the Type field will look like this:

To add, change, or remove options, select Admin > Manage Lists and edit the appropriate list.

Move an Issue to another Issue Tracker

If you organize issues into different folders, such as to divide by client or project, you may want to be able to move them. As long as the two issue lists share the same issue definition, you can move issues between them. Select the issue and click Move. The popup will show a drop-down list of valid destination issue lists.

Inherit Issue Tracker Settings

In some cases, such using multiple issue trackers in many different folders for multiple client projects, you may want to have these issue trackers share a single definition, i.e. have the same set of custom fields and options that you can update in one place. Issue definitions are not automatically "inherited" by subfolders, they must be defined in each folder locally. To share an issue definitions, define the "template" issue definition in a parent context and use the same name in the local context where you want to use the issue tracker. If you want to create a site-wide definition, define it in the "Shared" project.

When you define a new issue tracker definition in any folder, the name you select is compared first in the current folder, then the containing project, and finally the "Shared" project. If a matching name is found, a dialogue box asks you to confirm whether you wish to share that definition. If no match is found, a new unique definition is created.

Customize Notification Emails

Click Customize Email Template at the top of the issue administration page to edit the notification email that will be sent (based on notification rules and settings) whenever an issue is created or edited. By default, these emails are automatically sent to the user who created the issue, the user the issue is currently assigned to, and all users on the Notify List.

This email is built from a template consisting of a mix of plain text and substitution variables marked out by caret characters, for example, ^issueId^ and ^title^. Variables are replaced with plain text values before the email is sent.

For example, the variables in the following template sentence...

^itemName^ #^issueId^, "^title^," has been ^action^

...are replaced with plain text values, to become...

Issue #1234, "Typo in the New User Interface", has been resolved

You can also add format strings to further modify the substitution variables.

Complete documentation on the substitution variables and formats is shown on the template editor page.

Related Topics


expand all collapse all