Table of Contents

 guest
2025-06-01
     Issue/Bug Tracking
       Tutorial: Issue Tracking
       Using the Issue Tracker
       Issue Tracker: Administration

Issue/Bug Tracking


The LabKey Issues module provides an issue tracker, a centralized workflow system for tracking issues or tasks across the lifespan of a project. Users can use the issue tracker to assign tasks to themselves or others, and follow the task through the work process from start to completion.

Note: All issue trackers on your LabKey Server site are stored in the same underlying database table, and issue numbers are assigned sequentially as issues are added, regardless of the project or folder to which they belong. Issue numbers in any given project or folder list may not be contiguous, though will be in sequence.

Topics



Tutorial: Issue Tracking


This topic can be completed using a free 30-day trial version of LabKey Server.

The issue tracking tool helps you manage complex tasks, especially tasks that have multiple steps and require input from multiple team members. It is also useful for keeping track of small tasks that can easily fall through the cracks of a busy distributed team.

Issue Tracking Overview

Issues move through phases, using different status settings.

  • The open phase - The issue has been identified, but a solution has not yet been applied.
  • The resolved phase - A solution has been applied or proposed, but it is not yet confirmed.
  • The closed phase - The solution is confirmed, perhaps by the person who identified the problem, and so the issue is put to rest.

There are three main areas: a title section (with action links), a properties/status report area, and series of comments. Each comment includes the date, the contributing user, life-cycle status updates, and the body of the comment, which can include file attachments.

Set Up Tutorial

To complete this tutorial, you can use any folder where you have administrator access and it is suitable to do testing. For example:

  • Log in to your server and navigate to your "Tutorials" project, "Collaboration Tutorial" subfolder. Create them if necessary, accepting default types and settings.
    • If you don't already have a server to work on where you can create projects and folders, start here.
    • If you don't know how to create projects and folders, review this topic.

Create an Issue Tracker

First we add the issue tracker to the folder. There can be several different types of issue trackers, and issue definitions are used to define the fields and settings. In this case we need only a general one that uses default properties.

  • Navigate to the Collaboration Tutorial folder, or whereever you want to create the issue tracker.
  • Enter > Page Admin Mode.
  • Add an Issue Definitions web part on the left.
    • If you do not see this option on the list of web parts, you may need to enable the issues module in your folder. Select > Folder > Management > Folder Type, check the box for the Issues module, and click Update Folder.
  • Click (Insert New Row) in the new web part.
  • Give the new definition a Label. For the tutorial, use "My New Tracker".
  • Select the Kind: "General Issue Tracker" is the default.
  • Click Submit. Confirm that you are creating a new definition in your local folder.
    • If there is another issue tracker with the same name in the same folder 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.
    • Note: If you are sharing a definition, particularly with one in the "Shared" folder, be aware that changes you make here will change the definition for all issue trackers that use it.
  • Review the properties and default fields, but make no changes.
    • Notice that the setting for Populate 'Assigned To' Field from is "All Project Users". This means all users who have the role of "Editor" or higher and are members of at least one project security group.
    • Learn more about customizing issue trackers in the topic: Issue Tracker: Administration.
  • Click Save.


  • Click the Collaboration Tutorial link to return to the main page of the folder.
  • Add an Issues List web part on the left.
    • Confirm that your new default definition is selected.
    • Providing a title is optional. For the tutorial, you could use "Tutorial Issues".
    • Click Submit.
  • The page now has a new web part containing an empty issue list. The web part will have the title you gave it, or a default based on the issue list definition you used.
  • You can now delete the "Issue Definitions" web part to declutter the page. Select Remove from Page from the menu in the web part.
    • Note that removing a web part merely removes the UI panel. It does not remove the underlying content.
  • Click Exit Admin Mode in the upper right.

Grant Roles to Users

To be able to create issues, we need to have users to whom they can be assigned. The default setting we chose for the issue tracker includes all users who have the role of "Editor" or higher and are members of at least one project security group. When you first create a project, even you the site admin are not a member of a project group so cannot be assigned issues.

In this step we use the project group "Users" but you could also create your own group or groups of users; as long as they all have "Editor" access or better, they can be assigned issues under this setting.

  • Select > Folder > Permissions.
  • Click the Project Groups tab.
  • If you see "Users" listed, click it. Otherwise, type "Users" in the New Group Name box and click Create New Group.
  • In the Add user or group... dropdown, select yourself. You can add other users as well if you like.
  • Click Done in the pop-up.
  • Click Save and Finish.

Next we elevate the "Users" group to the Editor role.

  • Select > Folder > Permissions.
  • If necessary, uncheck Inherit permissions from parent.
  • Using the dropdown next to the Editor role, select "Users". This means that anyone in that group can open and edit an issue. Clicking the group name will open a popup listing the members.
  • Click Save.
  • Click the tab Project Groups.
  • Click Users. Notice that Editor is now listed under Effective Roles.
  • Click Done.
  • Click Save and Finish.

Use the Issue Tracker

Now you can open a new issue:

  • In the Issues List web part, click the New Issue button.
  • On the Insert New Issue page:
    • In the Title field: "Some Task That Needs to be Completed"
    • From the Assign To dropdown, select yourself.
    • In the Comment field, enter "Please complete the task." Notice below the field that you could update a supporting file attachment if needed.
    • Notice that the other required field (marked with an asterisk), Priority, has a default value of 3 already. Defaults are configured on the issues admin page.
    • Click Save.
  • You will see the details page for your new issue.
  • Click the Collaboration Tutorial link to return to the main tutorial page.

Notice that the new issue appears in the Issues List web part and you can click the title to return to the details. From the detailed view, you can also click links to:

  • Update: Add additional information without changing the issue status. For example, you could assign it to someone else using an update.
  • Resolve: Mark the issue resolved and assign to someone else, possibly but not necessarily the person who originally opened it, to confirm.
  • Close (available for resolved issues): Confirm the resolution of the issue closes the matter.
  • Reopen (available for resolved issues)): Reopen the issue, generally with a comment clarifying why it is not resolved.
  • More: Pull down a few more options:
    • New Issue
    • Create Related Issue: The newly created issue will have this issue's number in the "Related" field.
    • Email Preferences: Set when and how you would like to receive email notifications about this and other issues.
    • Print: Generate a printable view of the issue, including the comment history.
If you've added other users (real or fictitious ones as part of another tutorial) you could now assign your practice issue to one of them, then impersonate them to simulate a multi-user issue tracking process. When finished experimenting with your issue, you can close it:

  • Open the detail view of the issue by clicking the title in the issue list.
  • Click Resolve.
  • By default the Assigned to field will switch to the user who originally opened the issue (you); when there are more users in the group, you may change it if needed, so that a different person can confirm the fix.
  • Notice the options available on the Resolution field. The default is "Fixed" but you could select a different resolution, such as "By Design" for something that does not need fixing but might need explaining. For the tutorial, leave the default "Fixed" resolution.
  • Enter a message like "I fixed it!" and click Save.
  • You could return to the issue list to see how it looks now, then reopen it, or stay in the editor.
  • Now instead of a Resolve button, there is a Close button. Click it.
  • Enter a message if you like ("Well done.") and click Save.
  • Your issue is now closed.
  • See a working example of a similar issue list: Issues List.

Related Topics



Using the Issue Tracker


An Issue Tracker can be used to track any tasks or work that needs to be done by a group of users. Once added by an administrator, it usually appears to the user in an Issues List web part. The issue grid is like any other data grid offering options to sort, filter, customize, export, and chart the data. In addition an issue tracking workflow is preconfigured.

Issue Workflow

An issue has one of three possible phases: it may be open, resolved, or closed. Between the phases, updates can add information and the assignment can change from user to user.

To get started using issue trackers, review this topic:

Open and Assign Issues

When you open an issue, you provide the title and any other necessary information, and a unique issue ID is automatically generated. You also must assign the issue to someone from the Assigned To pulldown list, which is configured by an administrator. Other site users, i.e. stakeholders, may be added to the Notify List now or when the issue is updated later.

The person to whom the issue is assigned and all those on the notify list will receive notification any time the issue is updated.

Update an Issue

When an issue is assigned to you, you might be able to resolve it in some manner right away. If not, you can update it with additional information, and optionally assign it to someone else if you need them to do something before you can continue.

For example, if you needed test data to resolve an issue, you could add a request to the description, reassign the issue to someone who has that data, and add yourself to the notify list if you wanted to track the issue while it was not assigned directly to you.

You can update an open or a resolved issue. Updating an issue does not change its status.

Create a Related Issue

As you proceed to work through resolving an issue, it may become clear that there is a secondary or related issue. Tracking such issues independently can help with prioritization and clear resolution to all parts of an issue.

To create a related issue, select Create Related Issue from the More > menu while viewing any issue. You'll select the container in which to open the related issue, and the current issue will be prepopulated as "Related" to the new one.

An administrator can configure the default folder in which the related issue will be created, supporting a workflow where related tickets are used to 'escalate' or generalize an issue from many separate projects to a common location for a different group to monitor. You can change the folder from the dropdown if the default is not what you intend.

Resolve an Issue

Declaring an issue resolved will automatically reassign it back to the user who opened it who will decide whether to reopen, reassign, further update, or ultimately close the issue.

Options for resolution include: Fixed, Won't Fix, By Design, Duplicate, or Not Repro (meaning that the problem can't be reproduced by the person investigating it). An administrator may add additional resolution options as appropriate.

When you resolve an issue as a Duplicate, you provide the ID of the other issue and a comment is automatically entered in both issue descriptions.

Close an Issue

When a resolved issue is assigned back to you, if you can verify that the resolution is satisfactory, you then close the issue. Closed issues remain in the Issues module, but they are no longer assigned to any individual.

The Issues List

The Issues List displays a list of the issues in the issue tracker and can be sorted, filtered, and customized.

A note about filtering: When you filter the default view of the Issues List grid, your filters also apply to fields within the details view of individual issues. For example, if you filter out "Closed" issues, you will no longer see any closed issue IDs in the "Related Issues" section.

Some data grid features that may be particularly helpful in issue management include:

View Selected Details

To view the details pages for two or more issues, select the desired issues in the grid and click View Selected Details. This option is useful for comparing two or more related or duplicate issues on the same screen.

Specify Email Preferences

Click Email Preferences to specify how you prefer to receive workflow email from the issue tracker. You can elect to receive no email, or you can select one or more of the following options:

  • Send me email when an issue is opened and assigned to me.
  • Send me email when an issue that's assigned to me is modified.
  • Send me email when an issue I opened is modified.
  • Send me email when any issue is created or modified.
  • Send me email notifications when I create or modify an issue.
Click Update to save any changes.

Issues Summary

The Issues Summary web part can be added by an administrator and displays a summary of the "Open" and "Resolved" issues by user.

  • Click any user name to see the issues assigned to that user.
  • Click the View Open Issues link to navigate to the full list of open issues.

Not Supported: Deleting Issues

LabKey Server does not support deleting issues through the user interface. Typically, simply closing an issue is sufficient to show that an issue is no longer active.

Related Topics



Issue Tracker: Administration


This topic is under construction for the 25.7 (July 2025) release. For the previous documentation of this feature, click here.

An issue tracker can be configured to suit a wide variety of workflow applications. To define an issue tracker, an administrator first creates an Issue List Definition (the properties and fields you want), then creates 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.

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 Admin above the issues grid.

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.

Item Naming

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.

Assignment Options

You can control the list of users that populates the Assigned To dropdown field within the issue tracker. By default, the setting is "Site: Users", meaning any user logged into the site. You may select "Users" instead, meaning the project level "Users" group, which includes all users who are members of project level groups. You can also select another site or project group from the dropdown menu.

Only users who also have the "Editor" role (or higher) in the folder will be listed on the dropdown. This is required to allow them to report progress by editing any issue they are assigned.

Default User Assignment

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.

Customize Fields

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.

Default Values

To configure a field to provide users with a default value, click to expand it, then click Advanced Settings. The current type and value of 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:

Lookup/Selection Lists

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 > Manage Lists and edit the appropriate list.

URL Properties

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 > Go To Module > Query.
  • Open the issues schema, then your specific issue list definition.
  • Click Edit Metadata.
  • Expand the details for your custom field.
  • 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^ 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. 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.
  • Click Submit.

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.

Related Topics