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 small tasks that don't require more involved management tools, but can easily fall through the cracks of a collaborative effort.

Life Cycle of an Issue/Bug

Issues have three statuses/phases:

  • The open phase - The issue has been identified, but a solution has not yet been applied.
  • The resolved phase - A solution has been applied, 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.


  • The issue contains 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.
  • This issue has gone through the entire life-cycle: open, resolved, and finally closed.

Set Up and Use 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.

  • Return to the Collaboration Tutorial folder.
  • Add an Issue Definitions web part on the left.
  • Click (Insert New Row) in the new web part.
    • Give the new definition a Label, such as "Default Tracker", and leave "General Issue Tracker" selected as the Kind.
    • Click Submit. Confirm that you are creating a new definition in your local folder.
    • On the Issues Admin Page, under Configure Fields, for the option Populate the assigned to list from:, select All Project Users.
    • Review the other properties and naming conventions, but make no further changes.
    • 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 and click Submit.
  • The page now has an Issues List: defaulttracker web part containing a new empty issue list. Note that if you provided an optional title, that will be the name of the web part.
  • 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.

To represent the team members, we add a project group "Users".

  • Select (Admin) > 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.
  • Click Done in the pop-up.
  • Click Save and Finish.

Next we elevate the "Users" group to the Editor role. By default, the new group has the Reader role.

  • Select (Admin) > 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.
  • Click Save.
  • Click the tab Project Groups.
  • Click Users. Notice that Editor is now listed under Effective Roles.
  • Click Done.
  • Click Save and Finish.

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); you may change it if needed, so that a different person can confirm the fix.
  • Enter a message like "I fixed it!" and click Save.
  • Notice that 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 live example of a similar issue: Issues List.
  • See the LabKey issues list, where the LabKey staff tracks development issues: LabKey Issues List

Related Topics

Previous Step


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all