iReport
Case
Study
Version 3.1
Table Of Contents
Information You Will Need Before You
Start
Give Project Permissions to Users
and Groups
Introduction
This document follows
through an example of setting up and using the iReport system, following the
example of how Oakleaf Consultancy Limited use the iReport application.
It is intended to help the
reader in setting up and using their own iReport system, but it does not give
detailed information on each screen of the system. For this information, you
need to read the iReport User and Administration guides that are provided with
the iReport system. Rather, this document follows the process and stages of
setting up and using iReport.
Oakleaf Consultancy Limited
is a software consultancy, development and support company with several
developers, managers, customers and supported systems. Oakleaf needs to keep
track of bug reports and change requests raised internally within the company,
and by external clients that relate to the different systems, allocate these
issues to staff to work on, and track when the issues are fixed and can be
incorporated into new versions of software.
By following the steps
described below, you may get an idea of how to set up your own iReport system.
Installation
The first stage of setting up the system, is
obviously to install it.
Full instructions on how to
get and install iReport can be found on the Oakleaf web site.
When you install it, make a
note of the URL of your iReport installation. For example, http://www.oakleafconsultancy.com/iReport.
(Please be aware that you may also have to specify a port number of the Tomcat
web server – typically this might be 8080 - http://www.oakleafconsultancy.com:8080/iReport.
See the installation guide for more details).
Information You Will Need Before You Start
You will need a list of the
following information:-
1. User names, passwords and email addresses of all
users who will need access to iReport.
2. A optional set of groupings of users into groups for
example, in Oakleaf’s case, our groups are developers, managers and customers.
Users can only be a member of one group
at a time within iReport. Users can be in one big system-wide group, or several
smaller groups, it is purely for convenience in accessing some of the
administration functions.
3. A list of all projects that iReport needs to manage.
In Oakleaf’s case, this includes “iReport” (for reporting problems and
suggested enhancements to the iReport system itself), and Time Recording
(another software product that we develop). Projects can have whatever logical
structure you want. They may match up with real-life projects, sub-projects,
tasks, or groups of projects. It’s up to you.
4. An optional allocation of which groups of users are
able to work on which projects.
5. An allocation of which users are to work on which
project.
6. The name of a default responsible user of each
project. This user will “manage” the project, and have special privileges
within that project.
7. A list of all users who will be designated as
administrators of the system. Administrators have special rights and
responsibilities.
Logging In For The First Time
Open up a browser (e.g.
Internet Explorer) and type your iReport URL at the top of the screen. This
brings up the login screen.
When iReport is first
installed, a default user called “ADMINISTRATOR” with password “default” is
installed with the system.
Login as the ADMINISTRATOR
user.
When you have logged in, the
first thing you should do is change your password to some other value. Select
“Change Password” from the main menu and change it to a new value only you
know.
Creating the Groups
The next stage is to create
any groups that you have previously identified. This stage is optional, and you
do not have to create any groups at all if you don’t want to.
Choose the “Admin Console”
link from the main menu, and then select “Create a Group”.
Enter the name of the group
you want to create and then click on “Create” to create it. Repeat this process
for each of your groups.
Creating the Users
You should now create the
users of the system, filling in their user names, passwords, email addresses
and group names.
The email address is
important, as users will be notified when they become responsible for an issue,
or when someone updates an issue for which they are responsible. Users will
also receive a weekly update of the issues for which they are responsible.
You should also mark the user as being either a Normal user or an Admin user. Admin users can perform any action in the system, and have access to all projects, whether or not they are allocated to that project.
The system comes with a pre-defined group called BASE_DATA. If you do not create any groups of your own, put all your users in the BASE_DATA group.
Creating the Projects
Having created the users and groups, projects are now required. A project can be thought of as an area of work. It may correspond to a real project, part of a real project, a small task, or a whole set of projects. How you group work into projects for the purposes of iReport is up to you. Oakleaf has one project for each software product that it supports, so that the issues for each product can be kept separately from each other, and so that users working on one project do not necessarily have access to other problems relating to other projects.
Click on the “Create a
Project” link and fill in the details on the subsequent screen.
The Default responsible user
is the person who will receive notification that new issues have been created
for the project, effectively making them responsible for allocating these
issues to people to be worked upon.
As you can see, in this case, the user “eddiew” is the default user for the project:
Give Project Permissions to Users and Groups
Once projects have been
created, you should allocate users and groups of users to work on projects.
Click on the “Change Project
Permissions” link on the Admin menu and select the project you want to set
permissions for:
You will then be presented with a screen as shown below. This will allow you to allocate users to work on the project. By clicking on the link at the top of the page, you can also allocate groups to each project. Group users are allocated statically at the time of the action. If the users in the group change later, they need to be re-allocated.
Create Issues
You are now ready to begin
to use the system.
Let us say that the user
richardh thinks that a change is necessary to the Time Recording
project.
He logs on to the system as
richardh, using the password setup for him. He is then presented with the iReport
main menu.
There are several points to
note about the main menu.
1. richardh has only got permission to see one project –
“Time Recording”. If he had permissions for other projects, they would appear
in the list on the screen.
2. richardh is not an Administration user, so the Admin
Console link is not available to him.
Clicking on the “Time Recording” Project Name link will display a list of open issues for the Time Recording project for which richardh is responsible. In this case, no issues have been created for the project yet. He also has the option to view ALL issues for the project, even ones he is not responsible for.
richardh now needs to create
an issue for the bug he has found, so he clicks on “Post” under the “Issues”
section of the menu on the right of the screen. This brings up the “Post Issue”
screen, where he can enter details of the issue, including a title to identify
the issue within a list of issues, a detailed description of the problem, an
indication of the priority of the issue (the recipient will have higher
priority issues displayed higher up their issue list), a type of issue (e.g.
bug, change request, etc.) and a locations affecting field which is optional,
and contains more detailed information as to where the issues relates to, e.g.
Version 1.2
When all the data has been
entered, click on “Post”. This sends the issue to the default responsible user
for the project, in this case, “eddiew”.
eddiew will then be sent an
email by the system, similar to the following, to notify him that he has become
responsible for a new issue.
Allocation of Issues to Users
Once eddiew has been
notified by email of the existence of a new issue, he must decide what to do about
it. The most likely course of action is one of the following:-
1. Decide the issue is not relevant and close it.
2. Allocate the issue to another user to work on.
3. Update the issue and forward it back to the person
who raised it, asking for more information.
We will discuss option 2. at
this point. The other options will be followed later in the case study.
So, eddiew logs into the system, and is presented with the summary page showing him he now has one normal priority issue that he is responsible for. He can cross-reference his earlier email to the issue list by using the issue's unique issue number (in this case - 40).
He clicks on the “Time Recording” link in the table, to get a detailed listing of the Time Recording project issues. At this point he can see either the issues that he is responsible for, or ALL Time Recording project issues, no matter who is responsible for them.
He decides to look at this
issue's details so that he can decide what to do about it. He does this by
clicking on the issue title to display the issue detail screen.
He decides that user malcolmh needs to work on this problem, and so he needs to allocate the issue to malcolmh. He now clicks on “Change Responsibility” and selects malcolmh from the user list.
He is now presented with a
screen to enter a tracking report. A tracking report is simply a bit of text
that is appended to the issue, that tracks the reason for the transfer of
responsibility from user to another. He enters some meaningful text, and POSTs
the update. This causes the issue to be moved to malcolmh’s list, and for
malcolmh to be sent an email indicating that he is now responsible for the
issue.
Update of Issue
At this point, malcolmh will
have received an email similar to the following, telling him that he is now
responsible for an issue.
He can then logon and, using
the same procedure as eddiew above, select the detailed view of the issue. His
view of the issue contains an extra link to the tracking report added by eddiew
earlier. Clicking on this link will bring up a screen showing the detail of
that report.
At this point, malcolmh has
to decide what he will do about this issue.
He makes an estimate of the
work required in a text document and wants to attach this to the report, so he
clicks on “Post a Response”.
This brings up the following
screen, where he can enter the details of his update to the issue. He can also
click on the “Browse” button to allow him to choose the file to attach to the
report. Clicking on “Post” will send the update and the attachment and store it
in the system. The size of attachments is limited so that the system can not be
overloaded with huge amounts of data.
Once he has posted the
update, the main issue screen is redisplayed, showing the new information. At
this point, malcolmh is still responsible for the issue. He can either do more
work on the issue at a later time, and post more Reports to it, or he can
forward the issue back to the default responsible user, or to anyone else
working on the project, for their input.
You will notice that he
cannot CLOSE the report as he is not any of the following types of users:-
1. Default responsible user of the project.
2. A system administrator.
3. The person who raised the issue.
He decides that, having
given his estimate, he should return the issue to the project’s responsible
user, eddiew. So, he clicks on “Change Responsibility”, selects “eddiew” and
chooses, this time not to post a tracking report, hitting “Cancel Post and
Continue” instead.
At this stage eddiew then
becomes responsible for the issue again and is notified by email.
Closing Issues
Eddiew logs in and selects the
issue he has just been allocated. When he views the latest report that Malcolm
has added, there is a list of attachments for the report. When he clicks on the
attachment file name link, the text file that Malcolm attached to the report is
displayed.
Seeing malcolmh’s update to
the issue, he decides that no further work on this issue should be done at this
time, so he should close the issue.
Closing an issue simply
removes it from the day-to-day operation of the system. It is still present in
the system’s database, but will not appear on any user’s list of issues.
Having displayed the issue’s
details, he clicks on “Close” from the Issue menu on the right of the screen.
At this point, he is
presented with a tracking report screen. Where he can fill in the reason for
closure. He fills this in and posts the report.
The issue is now closed, and
an email is sent to both the issue’s originator and the person who was last
responsible for it to tell them that it was closed.
Searching For Issues
Sometimes it is necessary to
search for an issue that has already been created, based on criteria such as
text contained in the issue, whether the issue is open or closed, the person
who created the issue, the person who is responsible for the issue, etc.
In the case below, the user
is searching for all issues containing the text “estimate” and which were
created by user richardh. Criteria are not used in the search unless the
appropriate “Use Criteria?” check-box is checked.
When the user clicks on the
“Start Search” button, all the issues matching the requirements are displayed.
Issues that are closed, are
displayed in red.
The text of an issue can be
displayed by clicking on the link containing the title of the issue. It will be
possible to view, but not to update an issue that has already been closed.
A new search can be started
by clicking on the “New Search” button.
Reporting
There are two forms of
reporting within iReport.
1. Standard Reporting – implements a small number of
standard reports. E.g. All Open Reports, Reports closed in the last week,
reports closed in the last month.
2. Custom Reporting – allows the user to specify
criteria for the reports.
We look here at custom
reporting.
A user logs in and clicks on
the “Custom Reporting Tools” menu item on the main menu. This displays the
following screen.
The first thing to do is to
select the projects you want to report on by clicking on the “Change” button.
In this case, the user only has access to one project – “iReport”.
Then, you must choose the
criteria to be displayed on the report (“Display?”) and to be used as a basis
for selecting items for the report (“Use Criteria?”).
For example, if we want to
display a report containing the following:-
1. Issue Number
2. Issue Title
3. Issue Description
And that report is only to
contain those issues closed after 1st March 2004, and it is to be ordered by
Issue Number, the screen should be filled in as follows:-
Click on “Create Report”, and
another screen asking for a style of report is displayed.
Select on of the styles on
offer, and finally, the report is displayed. In this case the report contains
two issues, with very similar details! J
Further Help
If you need any further help or advice in using iReport, please contact Oakleaf Consultancy via our website at http://www.oakleafconsultancy.com/OCLiReport/index.jsp