The diagram below shows a screenshot of the iReport main-menu, together with information about which section of this user-guide contains information about the particular menu item. If you are viewing this user-guide online, please click on the section title to follow the link to it.

Introduction

What is iReport ?

iReport is a versatile tool designed as an aid to project management, development and support. It allows the members of a project team and users of software products to report problems arising with a product/project and to suggest new ideas. It then allows the software development team to allocate responsibility for solving these issues and to manage and track the progress of such problems through the bug-fixing/development and product release process in a structured, organised manner.

How is it Used ?

iReport creates representations of real world projects, which users (usually those working on the project in real life) can access. These users can then post issues to a project, which are assigned to the Default Responsible User for that project. An issue can be a bug that has been found with a product, a change request, or any other task relating to a project that needs to be allocated to a particular person in order to be actioned.

The Default Responsible User is the person responsible for allocating issues to other team members. They can read the issue and either deal with it themselves or assign it to another team member. This process of resolution/reassignment continues until the issue is resolved, at which point it should be sent back to the default responsible user, who can close it.

Issue closure prevents anyone from subsequently changing the issue, and removes it from the list of open issues for the project.

Throughout this process, all the users with access to the project can post reports to the open issue. Reports are essentially messages that are associated with an issue, and which usually provide some extra information about the issue, such as work already completed, further problems, or a more detailed description of the problem. These reports are designed to help the issue’s responsible user resolve the issue faster and more effectively. Any user with access to the project can see the current state of an issue, and read all reports associated with the issue.

Why is it Useful?

iReport is useful as it structures the issue tracking process, providing a centralised location for problems within a project to be aired and resolved. It also prevents problems from being overlooked as, once an issue has been raised in iReport, it will not disappear until the default responsible user has closed it. iReport also enforces a standard work-flow pattern, allowing problems to be assigned to the user most able to solve them, and allowing users to quickly and easily see what work they need to complete on a project.

iReport contains powerful reporting tools that allow issues, including closed issues, to be selected based on certain criteria and collated into an easily readable form. These tools are ideal for producing release notes for a product (e.g. listing all issues that were closed since the previous release) and for documenting currently open issues in a manner that is easy to print and save. The tools support a number of output formats, producing HTML that renders well both in browsers and in word processors such as Microsoft Word.

What Next?

The remainder of this document details how to use iReport. It assumes that an Administrator has already configured the system for use, including having set up projects, users and permissions correctly.

No administration information is given in this document, as this can be found elsewhere.

This document does, however, give plenty of information about posting issues and reports, and managing their lifecycle.

Logging In & Out

The Login Page

Before you can perform any actions using iReport, you must login to the system. Point your browser at the iReport URL, which will be provided to you by your system administrator. You will also have been given a username and password by your system administrator; please enter these into the correct boxes on the page, and then click the Login button. Assuming that you have entered your details correctly, you will be directed to the Overview page (see below). If something went wrong, you will be presented with an error message. You should remember to change your password from the default one given to you by your administrator (see below).

The Overview Page

Once you have successfully logged in, your browser will display the Overview page. This displays a table containing information about the projects that you can access, including the number of open issues that you are responsible for, and the priority of these issues. Clicking on the name of one of the projects will take you to the ‘View Issues’ page for that project.

A link on this page is provided to give you a similar list of ALLopen issues (rather than just the ones your are responsible for).

The Logout Page

Once you have finished your iReport session, you should logout. Click on the logout option from the list on the right hand side of the screen, and you will be directed to the logout page. If you confirm your logout by clicking ‘Yes’, you will be logged out and redirected to the login page. If you answer ‘No’, you will be redirected back to the overview page. Logging out is important as it helps to prevent unauthorised use of your iReport account by other users.

What are Projects?

A project in iReport is a container – it can represent a real world project, or it can represent some aspect of that project. A project contains issues (see below) which relate to the project, and has access-permissions associated with it in order to ensure that only authorised users can view information about it. This helps to ensure, for example, that users do not have access to projects in iReport that they do not work on in real life.

Most users cannot create, delete or modify projects – instead, they are limited to selecting a project in order to view its associated issues.

Project Selection

There are two ways of selecting a project:

Using the Overview screen

Using the Project Selection screen.

The overview screen (described above) gives the user slightly more information than the project selection screen, but can take slightly longer to load – as such, the project selection screen can be used to do the job faster.

The project selection screen simply displays a list of projects. Choose one of these and click the Select button, and the browser will be redirected to the View Issues page for that project.

Issue Management

Issues are at the heart of iReport; they describe problems that have arisen with a given project, and are assigned to specific users of the system in order to allow them to deal with the problems. Once an issue has been dealt with, it can be closed.

Viewing Your Issues

As described earlier, some overview information about the issues in the system, or at least the ones that you have permission to view, can be seen on the Overview page. This, however, only provides you with a summary of the number and importance of the issues that are open. You can find much more information about open issues on the View Issues page.

To access this page, you should follow one of the procedures described in the Project Selection section above. You will then be taken to the ‘View Issues’ screen for the selected project. This screen displays a list of the Issues attached to the selected project that you are currently responsible for, ordered by priority. You have the option to change the view to show all the current issues for the project, regardless of whether or not you are responsible for them, by clicking on the link at the top of the screen.

Clicking on an issue title takes you to a screen giving more detailed information about it, including a description of the problem, a list of locations affected by the problem, information about who created the problem and who is currently responsible for it, the date the issue was created, the priority of the issue, and its type. This screen may also display a series of links that, if clicked, will allow you to view the Reports that are attached to this Issue (see below).

You can return to the main list of issues for the project by clicking on the ‘View Issues’ link in the menu.

Posting Issues

You can create issues for any project that you have permissions to access. To create a new issue, you must select a project in which to create the issue. Once you have been taken to the ‘View Issues’ screen (see above), you should click on the ‘Post’ link in the main menu, underneath the ‘Issue’ heading. This will take you to the ‘Post Issue’ screen.

From here you must enter a title for the issue, and a brief description of the problem. The description should give an overview of the problem; more detailed information can be attached to the Issue as a report or series of reports (see below). You must also give the issue a priority and a type from the lists provided. You can optionally specify any locations that are affected by the Issue, e.g. a particular program, part or design.

Once all of these details have been entered, click the Post button. Your issue will be created and assigned to the project you selected. The issue will then appear in the Default Responsible User’s list of issues. An email will also be sent to the default responsible user for the project to inform them that it has been created. They may then reassign responsibility for the issue to another team member, or deal with it themselves (see below).

Searching For Issues

The main user menu has a "Search" link. Clicking on this link displays the Issue Search page. Using this page, you can search for issues that exist in the system, using various criteria.

For example, if you want to look for all issues that contain the word "logs", then click on the "Use Criteria?" check-box in the "Text of Issue Contains Phrase" row, and enter the word "logs" in the "Selection Criteria" text box.

Several criteria may be used within a single search. The criteria will be "AND"ed together. e.g. Issue Number is greater than 100 AND Issue Closed on 05/12/2003.

You may also use this screen to search for issues that have previously been closed. Only criteria whose "Use Criteria?" check box is selected will be used in the search.

When you have selected all the search criteria, click on the "Start Search" button. This will start searching the issues within the currently selected project.

When the search has been completed, the search results page will be displayed. Each issue that meets the criteria of the search will be listed. Issues highlighted in red are closed issues.

Clicking on the issue's title, will display the View Issues Page for that issue. If the issue has been closed, you will not be able to update it in anyway, but you will be able to view its reports and other details.

If you want to perform another search, click on the "New Search" button, and you will be taken back to the Issue Search page.

Changing Who Is Responsible For An Issue

As mentioned earlier, every project in the system has a user (the “default responsible user” who is initially responsible for every issue created for it. This user can change responsibility for the issue to another team member who, in turn, can assign responsibility to someone else in the team. This allows team members to keep track of who should be doing what to fix a particular issue, and ensures that whoever created the issue can keep track of who is currently responsible for fixing it, and contact them if required.

Whenever user responsibility for an issue is changed, an email is sent out to both the new user and the old user responsible for the issue to inform them of the change.

Only the following users can change who is currently responsible for an issue:

The issue’s currently responsible user.

The default responsible user for the issue’s project

System administrators.

If you want to change issue responsibility, select the relevant issue from the ‘View Issues’ screen for the particular project. When the issue’s page appears, click on the ‘Change Responsibility’ link in the menu on the right hand side of the screen. You will be presented with the list of users to whom you may reassign the issue. Select the user who you wish to assign responsibility to, and click the ‘Select’ button.

You will now be asked if you want to post a tracking report. This report can contain more information about why the issue is being reassigned. This tracking report is optional. You do not need to post additional information if it is not required.

Regardless of whether or not you do post the tracking report, once you click on either of the ‘Post’ or ‘Cancel Post and Continue’ buttons, responsibility for the issue will be changed, and emails will be sent out to the relevant people, as described above.

Closing Issues

Once an issue has been successfully resolved it should be closed. Closing an issue removes it from the active list for the project, and also informs the creator of the issue by email that the issue has been closed. Only the following users can close issues:

The issue’s creator

The default responsible users for the issue’s project

System administrators.

To close an issue, you should first select it from the ‘View Issues’ screen for a particular project and then click the ‘Close’ link in the menu on the right hand side of the screen. The issue will then be closed, and you will be asked if you want to post a tracking report (see below). Closing an issue does NOT remove it from the system. It can still be viewed using the reporting tools.

What are Tracking Reports?

Tracking reports are a special type of report that documents changes in the lifecycle of an issue. Users are prompted to post a tracking report when they change the responsible user for an issue, or when they close an issue. A user is never forced to post a tracking report, but they are strongly encouraged to do so, as it helps to document a reason for the change in status of the issue. More general information about reports can be found below.

Adding Reports

Why Reports?

Reports are items that are attached to a particular Issue in order to provide more detail about the problem, or to allow users to communicate their thoughts about the issue. Reports can be ‘chained’ together in a similar manner to that which is seem on Internet message boards, allowing users to have ‘conversations’ about topics relating to the issue that the reports belong to.

For example, one report might record the fact that a team member has sent an email to a client requesting more information about a particular problem. Another “chained” report could be added to this as a “sub-report” to document the reply to this email.

Viewing Reports

As has already been briefly mentioned, you can view the list of reports associated with an issue by clicking on the issue’s title when looking at the ‘View Issues’ page. This displays the information relating to the issue, including any attached reports. To view a specific report, you should click on its title; this displays the report’s main text. If the report has any children, links to them will be displayed at the bottom of the ‘View Report’ screen.

If someone has attached a file to a report when it was created (see below), there will be a link to that file in the header of the report. Clicking on the link will open up a copy of the attached file.

Posting a Report

To post a Report, you must first have selected the Issue you wish to attach it to from the ‘View Issues’ screen for the relevant project (see above). Once the correct screen is displayed, click the ‘Post’ link under the Report heading in the menu on the right hand side of the screen.

You will be taken to the ‘Post Report’ page. From here, you must fill in a title for the report and the description, which can be any information that you choose.

You may also choose to attach a file to the report. For example, a third-party may have sent you a description of the incident as a text file, or a word-processor document. To do this, click on the "Browse" button, and select the file in the "Choose file" window. When you save the report, the file will be uploaded to the server and will be visible to anyone viewing the report in the future.

When you have finished, click the ‘Post’ button, and you will be taken back to the screen for the Issue you added the report to. You should be able to see a link to the report you just created; this is now a permanent addition to the Issue, and can be viewed by other users.

Replying to a Report

In some cases, you may wish to post a reply to a particular report. To do this, you must select the report in question from its parent Issue’s page (see above for details on how to access this page). You will be presented with a screen showing the Report title and description. To reply to the report, click on the ‘Post a Response’ link in the menu on the right hand side of the screen. You will be taken to the ‘Post Report’ screen, which is described in the previous section. Once you have posted the report, it will be displayed on the parent Issue’s page, underneath the report you replied to and indented to the right slightly.

Reporting Tools

What are the Reporting Tools?

The Reporting Tools are a set of issue collation tools that allow you to perform simple searches on the issue database for one or more projects, and then to present the results in a predefined regular manner – usually one that lends itself well to being printed, saved on to disk, or copied into a word processing tool.

The tools are particularly useful for producing digests (“let me see the title and description of all of my open issues for project X”) or release notes (“let me see the title and description of all issues closed after DD/MM/YYYY”).

The tools come in two flavours – standard and customised. The standard tools are predefined searches that are run on the active project (i.e. the one most recently selected), and that are controlled by the system administrator. The customised tools allow you to generate simple reports of your own using the user-interface.

Standard Reporting Types

iReport is provided with a small number of standard reporting tools, including ones to display all the open issues for a project, all the issues closed in the last week, and all the issues closed in the last month. If you perform a particular custom report (see below) frequently, or require a report that is more complicated than those that the custom reporting tools can produce, then you should ask your system administrator if they can add a new standard reporting type.

To view one of the standard reports, you should first select a project, as described above. After this, you should click on the ‘Reporting Tools’ link in the main menu on the right. After this, you should select one of the reporting types from the list available, and then click on the Select button. Your browser will be redirected to the Style Selection screen – for more information about what to do next, see the Selecting the Presentation Style section below.

Customised Reporting

The customised reporting tools allow you to be a bit more specific about what it is that you want to search for, and also what information you want to be presented in the report. Custom reports also allow you to perform searches over multiple projects, something that the standard reporting types do not do by default.

To use the custom reporting tools, click on the ‘Custom Reporting Tools’ link in the main menu on the right hand side of the screen. If you have not already selected a project, or if you want to change the selected project(s), click on the ‘Change…’ button near the top of the screen and select the projects you want to use from the popup window that appears.

The main custom reporting screen is divided into four columns: ‘Field Name’, ‘Display?’, ‘Use Criteria?’ and ‘Selection Criteria’. The field name column, as you would expect, tells you what data that field contains. The next two columns contain checkboxes. Selecting the ‘Display?’ checkbox tells the tool that you want the data in that column to be displayed when you generate the report. Selecting the ‘Use Criteria?’ checkbox tells the tool to add the selection for that particular field into its search.

You can use the selection criteria to search for issues based on a number of different options. For example, you could specify only the issues created by User X, or the issues created after a specific date.

You can specify how you want the results to be ordered using the Order-By Assistant at the bottom of the screen; click the ‘Change…’ button at the bottom of the screen to launch this assistant.

Once you have finished putting your report together, click the ‘Create Report’ button. Your browser will be redirected to the Style Selection screen – for information on what to do next, see the next section.

Selecting the Presentation Style

Once you have generated your report, the tools will prompt you to select a presentation style. iReport is currently suppliedwith two standard styles, ‘iReport’ and ‘Word’. The ‘iReport’ style uses the standard iReport look-and-feel (orange and blue text) and is ideal for web-based presentation, or for saving to disk and reloading from time to time. The ‘Word’ style uses the Microsoft Word heading look-and-feel, as used in this document. This makes it ideal for cutting-and-pasting into a word document.

To use a style, select it from the list. The preview pane below the list will update to give an example of the style. If you are satisfied with the preview, click the Select button. A new window will pop up containing the reporting results formatted in the specified style.

The results are displayed as a web page using the style selected - in this case, MS Word.

User Settings

Changing Your Password

It is important to change your password from the default one given to you by the administrator as soon as possible, for security reasons. It is also good practice to change your password regularly, and to choose passwords that are not easy to guess.

To change your iReport password, you should select the ‘Change Password’ link from the main menu on the right hand side of the screen. You will be taken to the ‘Change Password’ screen where you must enter your new password, and a confirmation of your new password. Assuming that you enter these correctly, your password will be altered after you click on the ‘Change’ button.