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 (Admin) > 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 (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. 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 (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. 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.
- See the LabKey issues list, where the LabKey staff tracks development issues: LabKey Issues List
Related Topics
