An issue tracker can be configured by an administrator to suit a wide variety of workflow applications. To define an issue tracker, you first create an Issue List Definition
(the properties and fields you want), then create an Issues List
using it. Multiple issue trackers can be defined in the same folder, and issue list definitions can be shared by multiple issues lists across projects or even site-wide
Set Up an Issue Tracker
First, define an Issue List Definition
. Most issue trackers use the "General Issue Tracker" kind. The Label (Name) you give it can be used to share definitions across containers
- Add an Issue Definition web part.
- Click (Insert new row).
- Choose the Label that will identify this issue list.
- For the Kind, most issue trackers use "General Issue Tracker" as described in this topic.
Issues List Properties
When you first create an issues list, you will be able to customize properties and fields. To reopen this page to edit an existing issue tracker's definition, click the Admin
button on the issues list grid border.
The issues admin page begins with Issues List Properties
Define properties and customize Fields
before clicking Save
. Details are available in the following sections.
Comment Sort Direction
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.
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 "Tasks", "Tickets", or "Opportunities" depending on the context.
You can control the list of users that populates the Assigned To
dropdown field within the issue tracker.
- By default, the setting is "All Project Users" (as shown as placeholder text). This option includes all users who are BOTH of the following.
- Instead, you can select one specific group from the dropdown menu. Both site and project groups are available, but only users who also have the "Editor" role or higher will be available on the assignment dropdown.
Note: Administrators are not automatically included when "All Project Users" is selected, unless they are explicitly added to some project-level security group.
You also have the option of selecting the Default User Assignment
for new issues. This can be useful when a central person provides triage or load balancing functions. All users in the selected Assigned To group will be included as options in this list.
Default Folder for Related Issues
When a user creates a related issue from an issue in this tracker, you can set the default folder for that issue. This is a useful option when you have many individual project issue trackers and want to be able to create related issues in order to 'escalate' issues to a shared dashboard for developers or others to review only a subset.
Default folders can be used with Shared issue list definitions, though apply on a folder by folder basis. Set a folder-specific value for this field along with other folder defaults
Click the Fields
section to open it. You will see the currently defined fields. General Issue Trackers (the default Kind) include a set of commonly used fields by default, some of which are used by the system and cannot be deleted.
You can use the field editor
to add additional fields and modify them as needed.
- Check the Required box for any fields that you want users to always populate when creating an issue. Use default values when appropriate.
- Click the icon on the right to expand field details, including lookup targets and advanced settings.
- Use the six-block handle on the left to drag and reorder fields.
- Any field showing a on the right is not required by the system and may be deleted if not needed.
- Fields that are lookups, shown here in the case of the "Resolution" property, present users with a picklist menu of options. The field details panel shows the list that will be used; here "mynewtracker-resolution-lookup". Expand the field details if you want to change the lookup. Click the lookup target name to go to the list it is looking up from.
To configure a field to provide a default value, click
to expand any field, then click Advanced Settings
. The current type and value for the default will be shown (if any).
The Default Type
can be fixed, editable, or based on the last value entered. Select the type of default you want from the dropdown. If you change it, click Apply
and then Save
; reopen the editor if you want to now set a default value.
To set a default value for a field, click
to expand any field. Click Advanced Settings
. Click Set Default Values
to open a page for editing all fields with default values enabled may be edited simultaneously:
Hide Protected Fields
To require that a user have insert permissions (Submitter, Editor, or higher) in order to see a given field, select PHI Level > Limited PHI
on the Advanced Settings
popup. This allows certain fields to be used by the issue tracking team, but not exposed to those who might have read-only access to the issue tracker.
Learn more in this topic:
If you want 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 typically named combining the issue tracker name and field name. When editing the fields in an issue tracker definition, the name of the lookup target will link to the selection list. For example, in an issue tracker named "My New Tracker", the selection list for the "Resolution" field is named Lists.mynewtracker-resolution-lookup:
Click to open it. It looks like this (by default) and can be edited to change the available selections:
When a user is resolving an issue, the pulldown for the Resolution field will look like this:
To add, change, or remove options, select (Admin) > Manage Lists
and edit the appropriate list.
If you would like to have a custom field that links to an outside resource, you can use a URL field property
. To apply a URL field property, do not use the issue tracker admin page; instead you must edit the metadata for the issue tracker via the query browser:
- Select (Admin) > Go To Module > Query.
- Open the issues schema, then your specific issue list definition.
- Click Edit Metadata.
- Expand the details for your custom field using .
- Set the URL Property here.
- Save your change and return to see that the values will now link to the target you specified.
Share an Issue List Definition
In some cases, you may want to use the same issue list definition in many places, i.e. have the same set of custom fields and options that you can update in one place and use in many. This enables actions like moving issues from one to another and viewing cross-container issues by using a grid filter like "All folders".
Issue list definitions can be shared by placing them in the project (top-level folder), for sharing in all folders/subfolders within that project, or in the /Shared project, for sharing site-wide. Note that an issue list definition in a folder within a project will not be 'inherited' by the subfolders of that folder. Only project level issue list definitions are shared.
When you define a new issue list 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. An important note is that if you create a child folder issue list definition first, then try to create a shared one with the same name, that original child folder will NOT share the definition.
Issue list definitions are resolved by name. When you create an issue tracker in a folder, you select the definition to use. If the one you select is defined in the current project or the /Shared project, you will be informed that the shared definition will be used.
Customize the Local Version of a Shared Issue Tracker
When you click the Admin
button for an issue tracker that uses a shared issue list definition, you will see a banner explaining the sharing of fields, with a link to manage the shared definition.
You can edit Issues List Properties
for the local version of this issue tracker, such as the sort direction, item name, and default user assignment. These edits will only apply to your local issue tracker.
Note that you cannot edit the Fields
or their properties here; they are shown as read only. Click the words source container
in the banner message, then click Admin
there to edit the fields where they are defined. Changes you make there will apply to all places where this definition is shared.
Note that you can edit the default values
for field properties in your local container. To do so, open the default value setting page for the shared definition, then manually edit the URL
to the same "list-setDefaultValuesList.view" page in your local container. Defaults set there will apply only to the local version of the issue tracker. You can also customize the dropdown options presented to users on the local issue tracker by directly editing the XML metadata for the local issue tracker to redirect the lookup.
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 dropdown list of valid destination issue lists.
Customize Notification Emails
Notification emails can be sent whenever an issue is created or edited in this folder. 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
Click Customize Email Template
in the header of the issues list to edit the template used in this folder.
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^
. 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. More details can be found in this topic: Email Template Customization
Issue Tracking Web Parts
Web parts are the user interface panels that expose selected functionality. If desired, you can create multiple issue trackers in the same folder. Each will track a different set of issues and can have different fields and properties. To do so, create additional issue definitions. When you create each Issues List web part
, you will select which issue list to display from a drop down menu.
Issues List Web Part
Once you have created an issue definition in the folder, you can add an interface for your users to a tab or folder.
- Add an Issues List web part.
- Select the issue definition to use.
- If you don't provide a web part Name, a generic one based on the name of the issue definition will be used.
Issues Summary Web Part
The Issues Summary
web part displays a summary of the Open and Resolved issues by user. This can be a useful dashboard element for managing balancing of team workloads. Add this web part to a page where needed
. You can give it a custom name or one will be generated using the name of the issue definition.
Clicking any user Name
link opens the grid filtered to show only the issues assigned to that user. Click View Open Issues
to see all issues open in the issue tracker.
Note that a given project or folder has only one associated Issues module, so if you add more than one Issues List or Summary web part associated with a given issue definition, both will display the same data.