This topic is under construction for the 22.7 (July 2022) release of LabKey Server. For current documentation of this feature, click here.
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, then create an Issues List
. 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.
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, 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 "Bugs", "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.
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 tracker definitions, though apply on a folder by folder basis.
Click the Fields
section to open it. You will see the currently defined fields. General issue trackers 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 as needed to suit any application.
- 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 shows the list that will be used; here "mynewtracker-resolution-lookup". Expand the field if you want to change the lookup.
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 named combining the issue tracker name and field name. For example, in an issue tracker named "My New Tracker", the selection list for the "Resolution" field is named Lists.mynewtracker-resolution-lookup and looks like this (by default):
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 tracker 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.
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.
Inherit Issue Tracker Settings
In some cases, such as 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 when creating another issue definition there. The server will confirm that it found an existing definition in the parent context to reuse. 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
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.
1,1 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.