USER GUIDE DATACOM JIRA ISSUES MANAGEMENT TUESDAY, 22 APRIL 2014 Version 1.1.0
Contents 1 INTRODUCTION... 3 2 KEY CONCEPTS TO UNDERSTAND... 4 2.1 Assigning vs. Progressing an Issue... 5 2.2 Workflow... 6 2.3 Resolving an Issue... 7 3 CREATING A NEW ISSUE... 9 4 SEARCHING FOR ISSUES... 11 4.1 Dashboards... 11 4.2 Projects... 12 4.3 Filters... 12 4.4 Quick Search... 13 5 VIEWING AN ISSUE... 14 6 EDITING AN ISSUE... 16 7 WATCHING AN ISSUE... 19 8 NOTIFICATIONS (EMAIL ALERTS)... 21 9 ESTIMATES AND TIME LOGGING... 22 10 HELP... 23 10.1 Login Details... 23 10.2 Forgotten Password... 23 10.3 Change Password... 24 10.4 Further Help... 25 Datacom JIRA User Guide.docx Page 2 of 25
1 Introduction This is a user guide for Datacom s web based issue management tool, JIRA. JIRA has replaced SDM as the corporate issues management tool provided to clients and Datacom staff. The guide is intended as a procedural guide for performing functions on the system and assumes the reader has a basic level of familiarity with the processes involved in issue management related to all projects carried out by Datacom Systems and Programming. This document commonly refers to an issue, reflecting how the term is used within JIRA for consistency purposes. In JIRA, each issue has a type (e.g. Defect, Change Request, Query/Investigation, Task etc.). The word Issue is therefore used in a generic sense, rather than an actual application or project issue. As a one-off exercise, all users are encouraged to first follow the Datacom JIRA Quick Start guide to access shared Dashboards and Filters which make the JIRA experience more efficient and user-friendly. Some menus and areas of JIRA may relate to Agile. This is separate to the core Issues Management functionality and is currently being trialled. The JIRA instance can be accessed from: https://jira.onedatacom.com. Datacom JIRA User Guide.docx Page 3 of 25
2 Key Concepts to Understand At any point in time an issue has a certain status. A workflow exists which determines the next statuses to which the issue can progress. Each button (as highlighted below) represents an action which transitions the issue to a different status. The workflow action buttons displayed vary, depending on the issues current workflow status and which workflow is applied to the project. Note: When the Workflow dropdown is enabled, further workflow action options are available by clicking it. Datacom JIRA User Guide.docx Page 4 of 25
When a workflow action button is clicked, a pop-up screen is usually displayed to the user. The popup prompts the user for information relevant to that particular workflow transition. E.g: When the Set to In-Progress button is clicked, the changes are saved to the issue and it is transitioned to the new workflow status and assignee. If Cancel is clicked instead, the issue is not updated and it does not progress to the new status. 2.1 Assigning vs. Progressing an Issue An issue should be progressed to a new status only when the next task required on an issue represents a whole new stage in its workflow (e.g. to move from Open to In Progress ). When the status of the issue has not changed, but a different person needs to perform a task on it, the issue should be assigned to the new user, without progressing it. E.g. an issue has a status of Open and is currently assigned to DatacomUserX. DatacomUserX needs some further information from the client, so they click Assign and assign it to ClientUserY. ClientUserY adds a comment to the issue when they assign it back to DatacomUserX. During this process, the status remains at In Progress. Only when the development work is complete does DatacomUserX progress the issue to Datacom Testing status. The Sub-Status field is provided to show the specific type of work being performed on an issue Datacom JIRA User Guide.docx Page 5 of 25
2.2 Workflow The actual workflow used by a project can vary, but the following describes a common workflow used: Start / Create Issue Responsibility for the Issue primarily sits with Datacom On-Hold Open Change Request Required Reopened In Progress Future Phase For Datacom Release Datacom Testing Resolved Responsibility for the Issue primarily sits with the Client For Release Closed Finish Datacom JIRA User Guide.docx Page 6 of 25
The following provides a brief description of each status in the workflow: Status Open Reopened On-Hold Change Request Required Future Release In Progress For Datacom Release Datacom Testing Resolved For Release Closed Description The issue is not currently being actively progressed, so it is effectively in a pending queue. It may be going through a triage process, or it is awaiting assignment to progress. The issue has been through the main Datacom workflow and was resolved, but the client has identified something with the resolution such that it requires Datacom to review it again. This status is very similar to Open, but it identifies the fact that the issue has already been through the workflow. The issue has been placed on-hold and no further work should take place, unless otherwise advised (usually by the client). The issue has been identified as needing to be treated as a Change Request. Approval is required from the client on that basis, before Datacom can do further work on the issue. The intention is to progress the issue, but it is outside the scope of the current release. The issue is actively being worked on. The issue has passed the Datacom Development stage and is ready to be deployed into the Datacom Test environment for Datacom Testing. The issue has passed the Datacom Development stage and is being tested by Datacom. Datacom have completed their work as far as possible. This has either resulted in a fix which needs to be tested by the client, or the issue was not fixed and the reason provided. This is a key status as it represents an effective change in issue ownership, from Datacom over to the Client. The client has tested the fix provided and it passed. The fix is now awaiting deployment into another environment (e.g. Production). The issue has been accepted by the Client as complete and has been closed. Closed issues cannot be reopened. Instead, a new issue should be created and a link added in the new issue, back to the original issue. 2.3 Resolving an Issue 2.3.1 Resolution An important event in the workflow of an issue is when it gets Resolved. This status effectively means the issue has become primarily the client s responsibility. Before an issue has been resolved, the primary responsibility for the issue is assumed to be with Datacom. From the Resolved status, the client can progress it through to closure, or choose to re-open it if they do not accept the proposed resolution. Datacom JIRA User Guide.docx Page 7 of 25
2.3.2 Developer Resolution It is often a Datacom developer who needs to identify the resolution of the issue s as part of them implementing a fix or change. However, at this stage, responsibility for the issue remains with Datacom as there is likely to be further testing etc. required, before it can be released to the client. From a JIRA perspective, the issue should not therefore be Resolved as this transfers responsibility over to the client. To accommodate this situation, an additional field called Developer Resolution has been added. The values of Developer Resolution match those of Resolution. The developer sets the Developer Resolution field when they progress the issue from In Progress to Datacom Testing. The tester then tests the issue and when the issue passes testing, the tester resolves the issue and sets the actual Resolution value. The actual resolution value should be the same as the Developer Resolution value. Datacom JIRA User Guide.docx Page 8 of 25
3 Creating a New Issue Depending on the role which you have been assigned on a project, you may have the access right to create new issues. Where this permission exists, a Create Issue button is displayed, as below: When the Create Issue button is clicked, a screen similar to the one below is displayed: Fields marked with a * are mandatory and must be specified. Datacom JIRA User Guide.docx Page 9 of 25
Further information about a field s options is available by clicking the icon. To keep the Create Issue screen open and create another issue, check the Create another checkbox. Once all the required information has been entered, click the Create button to save and create the new issue. Datacom JIRA User Guide.docx Page 10 of 25
4 Searching for Issues A number of methods are available to a user to search for an issue. These include: 4.1 Dashboards Dashboards are intended to provide an area which gives the user a view of the issues and information relevant to their work. Dashboards are likely to be the area in which users spend most of their time when using JIRA. The My Issues shared dashboard shows issues which are currently assigned to the user, grouped by different stages of the workflow: If required, a user can create their own Dashboards and manage their dashboards by clicking the down arrow next to the Dashboards menu item and then clicking Manage Dashboards. The same functionality can be accessed via the Tools dropdown on the Dashboards screen. Datacom JIRA User Guide.docx Page 11 of 25
4.2 Projects The Projects menu allows the user to view information and issues for a single Project. Note: The Summary tab provides access to a number of reports and an Activity Stream showing recent changes made to issues in the project. The Issues tab provides access to a number of pre-set Filters, specific to the project. Clicking on one of the Filters links takes the user to the Filters tab, as described in section 4.3 - Filters, and applies the necessary criteria for that Filter. 4.3 Filters Filters provide a flexible method of searching for issues. The user can either apply a favourite Filter or create their own Filter by specifying the required criteria. Custom Filters can be saved for future re-use. Datacom JIRA User Guide.docx Page 12 of 25
The Filters screen is shown here: Clicking on a Favourite filter automatically applies that filter and displays matching issues. New Filters are created by clicking on New Filter, choosing basic or advanced mode via Basic or Advanced mode, then specifying the required criteria. Clicking the display matching issues. The naming convention applied to the shared Filters is as follows: <Client> - <Scope of Assigned To> - <Status>, <Sorting Field> e.g. All My Open, by Project will execute the Filter and 4.4 Quick Search The Quick Search textbox can be used when the user already knows the Issue Key they want to open. Enter the key into the textbox and press the Enter key to open the issue. Datacom JIRA User Guide.docx Page 13 of 25
5 Viewing an Issue A number of different methods are available for the user to search for an issue, as described in the section: 4 - Searching for Issues. Once an issue has been found, the user can view the details of the issue. The most common methods are described below. 1. By clicking the Issues Key or Summary value from a Dashboard: 2. By clicking the Issues Key or Summary value from Issues search: Datacom JIRA User Guide.docx Page 14 of 25
3. By entering the Issue s Key value into the Quick Search : Datacom JIRA User Guide.docx Page 15 of 25
6 Editing an Issue Once an issue has been opened for Viewing, a screen similar to the one below is displayed: On this screen, a number of buttons are available (as highlighted), allowing the user to perform an action on the issue: 1. Edit open an Edit screen to view and edit all details of an issue. 2. Comment add a comment to the issue. 3. Assign assign the issue to a different user, without changing its workflow status. 4. More - includes: a. Attach Files allows a file to be attached to the issue. b. Attach Screenshot allows a screenshot to be uploaded to the issue. c. Add Vote user can vote for a change to show they would like it to be implemented. d. Watch Issue by watching an issue it will appear in the user s Watched Items area (e.g. the My Watched Issues Dashboard). e. Link where there is an associated issue a link can be created between them (e.g. blocks, clones, duplicates, relates to). f. Clone creates a clone of the current issue, but with a different Summary. Datacom JIRA User Guide.docx Page 16 of 25
Clicking on the Edit button displays a screen similar to the one below and allows the user to update the details of the issue: When the necessary changes have been made, click the Update button to commit the changes. Datacom JIRA User Guide.docx Page 17 of 25
The Edit and Workflow progression options can also be accessed directly from the search results of a Dashboard or Filter by clicking the button below, when the mouse is hovering over an issue: Datacom JIRA User Guide.docx Page 18 of 25
7 Watching an Issue A lot of screens and notifications in JIRA are targeted towards issues which are currently assigned to the current user. Issues not assigned to the current user are often excluded. If an issue is of particular interest to a user, the user can select to Watch it. The My Watched Issues dashboard displays these watched issues, regardless of their status, or who they are currently assigned to. Notifications are also sent out to Watchers of the issue, upon most issue events. To Watch an issue, open the issue and click the Start watching this issue link as highlighted below: At any time, the issue can be removed from Watching by opening the issue and clicking Stop watching this issue. Taking this feature a step further, a feature called Autowatch is available within each user s profile. When enabled for a user, the user will automatically Watch each issue which they create or add a comment to. To enable Autowatch on your profile, follow these steps: 1. Once logged in, click the down arrow next to your login name and click Profile. Datacom JIRA User Guide.docx Page 19 of 25
2. Click the pencil icon against Preferences to edit them. 3. Change the dropdown of Autowatch to Enabled. At any time, this setting can be changed back to Inherit from global settings or Disabled. Datacom JIRA User Guide.docx Page 20 of 25
8 Notifications (Email Alerts) When certain events occur on an issue, notifications are automatically sent to different members of the project to inform them of the event. Notifications take the form of an email. Each notification contains a link to the issue in JIRA and provides details of what has changed. By clicking the link in the email, a browser window is opened to display the issue details. Depending on the type of event and the configuration of the project, the actual users which receive notifications, varies. The following are examples of events which cause notifications to be generated: 1. Issue Created 2. Issue Updated 3. Issue Assigned 4. Issue Resolved 5. Issue Closed 6. Issue Commented 7. Issue Comment Edited 8. Issue Reopened 9. Issue Deleted 10. Issue Moved A common project setup will result in the Current Assignee and all Watchers of the issue being notified of an event. Additionally, individual users can be granted notification of the specific types of events which they are interested in. Datacom JIRA User Guide.docx Page 21 of 25
9 Estimates and Time Logging Some templates enable recording of: 1. Estimated total amount of work required on an issue 2. Estimate To Complete 3. Amount of time Worked on the issue. Only users in one of the Datacom roles can log time again an issue. Details on how to use this functionality is available from: https://confluence.atlassian.com/display/jira/logging+work+on+an+issue Summary: Notes: 1. The Estimate, Remaining and Logged fields are shown in the Time Tracking section of the Issue Details screen. 2. Time can be logged by clicking on the + icon next to the Time Tracking section. 3. Time can also be logged during issue status transitions. The fields are available on the Time tab of the transition popup screen. 4. All time logged against an issue can be viewed from the Work Log tab on the Issue Details screen. Users with the Datacom User role can edit/delete their own work logs. Users with the Datacom Power User role can edit/delete any work logs. 1. There is currently no integration between JIRA Work Logs and OneTime. a. This may be possible in the future but there is no timeframe for this work at present. b. For now, time still needs to be manually entered into OneTime, even if JIRA Work Logs are being used. 2. Reporting of time worked is only available on a per issue basis, not within a specific time period. E.g. is it not possible to report on how much work was spent on issues between date A and B. It is only possible to see that for issue X, Y hours/days have been worked. Datacom JIRA User Guide.docx Page 22 of 25
10 Help 10.1 Login Details Field Description Username - For clients, enter your email address. - For Datacom staff, enter your Datacom login (excluding the DATACOM\ part). Password - For clients, this is the password specified during the setup process. The introductory email provides a link to change your password before first login. - For Datacom staff, enter your Datacom login password. 10.2 Forgotten Password If you have forgotten your password, you can reset it by clicking on the Can t Access your account? link from the login page. This takes you to the screen below where you can enter your username (email address) and an email is sent to that address, with a link to reset your password. Datacom JIRA User Guide.docx Page 23 of 25
10.3 Change Password It is advisable that you change your password on a regular basis. To change your password: 1. Login to JIRA with your username and password. 2. Click the downward arrow next to your login name. 3. From the displayed menu choose Profile. 4. Click Change Password from the page displayed. 5. Enter your current password and new password in the fields provided. 6. Click Update to apply the change. Datacom JIRA User Guide.docx Page 24 of 25
10.4 Further Help The product documentation provided for the JIRA product can be accessed from the profile dropdown (the down arrow next to your login name) and then Online Help. JIRA is a widely used commercial issues management product. Further user guides and documentation can be found at: https://confluence.atlassian.com/display/jira/jira+user's+guide If you have any other issues or queries with Datacom s JIRA implementation, please email jirasupport@datacom.co.nz. Datacom JIRA User Guide.docx Page 25 of 25