#LyX 1.6.7 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass scrbook
\begin_preamble
\input{preamble.tex}
\end_preamble
\options twoside,pointlessnumbers,obeyspaces
\use_default_options true
\language english
\inputencoding utf8
\font_roman lmodern
\font_sans helvet
\font_typewriter courier
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\float_placement H
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\papersize letterpaper
\use_geometry false
\use_amsmath 2
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 2
\tocdepth 2
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 2
\paperpagestyle default
\bullet 0 5 11 -1
\bullet 1 5 24 -1
\bullet 2 0 0 -1
\tracking_changes false
\output_changes false
\author ""
\author ""
\end_header
\begin_body
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
input{chapter.tex}
\end_layout
\end_inset
\end_layout
\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "cha:Software-Requirements-Specifications"
\end_inset
Software Requirements Specifications
\end_layout
\begin_layout Standard
\shape up
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
epigraph{Complexity kills.
It sucks the life out of developers, it makes products difficult to plan,
build and test, it introduces security challenges, and it causes end-user
and administrator frustration.}{Ray Ozzie}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Repetition can happen when gathering requirements.
If software requirements specifications (SRS) are written without the DRY
principle in mind, reports might be specified that are variations of the
same report.
This can result in several distinct reports, a duplication of effort.
\end_layout
\begin_layout Standard
For example, changing the column order, changing the sort order, grouping
the data differently, providing different subtotals, and so forth, can
be part of the same report.
Even though the reports may look fairly different visually, the report
specifications must strive to combine similar reports.
Take the time you need during requirements gathering to ensure you do not
create duplicate reports.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
If it looks like requirements have been copied, pasted, and slightly changed,
chances are they are the same report.
Do not duplicate requirements.
Rather, write the requirements in a general manner to combine similar cases.
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Before creating customer-facing reports (that are not
\emph on
ad hoc
\emph default
), developers must know how the business will use them.
Report specifications produced before implementing the reports give senior
developers the chance to eliminate duplication by merging similar reports.
\end_layout
\begin_layout Standard
In this chapter:
\end_layout
\begin_layout Itemize
\series bold
Business Requirements.
\series default
What business need is met by the report?
\end_layout
\begin_layout Itemize
\series bold
Security.
\series default
Who can run the report? Who can see sensitive information?
\end_layout
\begin_layout Itemize
\series bold
Title and Subtitle.
\series default
How is the report categorized?
\end_layout
\begin_layout Itemize
\series bold
Physical Location.
\series default
Where are the report files found?
\end_layout
\begin_layout Itemize
\series bold
Parameters.
\series default
What information does the report need to execute? What are the defaults?
\end_layout
\begin_layout Itemize
\series bold
Query Statement.
\series default
Where is the statement located?
\end_layout
\begin_layout Itemize
\series bold
Data Columns.
\series default
What information does the report include?
\end_layout
\begin_layout Itemize
\series bold
Design.
\series default
How should the report output be structured?
\end_layout
\begin_layout Itemize
\series bold
Variations.
\series default
How can the same report be reused to combine similar information?
\end_layout
\begin_layout Itemize
\series bold
Test Cases.
\series default
What output values are expected for a given set of inputs?
\end_layout
\begin_layout Section
Business Requirements
\end_layout
\begin_layout Standard
At a minimum, the business requirements section of the software requirements
specification (SRS) includes a sentence or two that describes the problem
the report solves for the business.
As most corporate reports exist to simplify or expedite information (that
will be used to make business decisions), the business requirements section
is critical.
Additionally, the business requirements section should answer the following
questions:
\end_layout
\begin_layout Itemize
What is the report's purpose?
\end_layout
\begin_layout Itemize
How will the report be used?
\end_layout
\begin_layout Itemize
Who is going to use it?
\end_layout
\begin_layout Itemize
How will the report be integrated?
\end_layout
\begin_layout Itemize
Who is responsible for the report requirements?
\end_layout
\begin_layout Itemize
Who knows where to find the data?
\end_layout
\begin_layout Standard
For enterprise systems, to avoid duplicating the business reasons for the
report, the business requirements section can be linked to requirements
gathering and documentation software.
\end_layout
\begin_layout Section
Security
\end_layout
\begin_layout Standard
This part of the business requirements involves identifying the following:
\end_layout
\begin_layout Itemize
Authentication
\end_layout
\begin_layout Itemize
Authorization
\end_layout
\begin_layout Itemize
Integration
\end_layout
\begin_layout Subsection
Authentication
\end_layout
\begin_layout Standard
Identify the roles of the individuals who are allowed to run the report.
\end_layout
\begin_layout Subsection
Authorization
\end_layout
\begin_layout Standard
Determine what data may be included, and what data must be included, in
the report.
Identify potential privacy issues and address them as soon as possible.
For example, managers might have permission to create reports on the salaries
of any employee in their department, and no other.
\end_layout
\begin_layout Subsection
Integration
\end_layout
\begin_layout Standard
Whenever data from one system is used as input to another system, it creates
a potential entry point for security leaks.
To help reduce the amount of information about the internal workings of
your system that are potentially revealed to the world:
\end_layout
\begin_layout Itemize
Remove all
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
files from the web server.
Keep these in a source code repository and on developer machines as necessary.
Unless you are using
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperserver{}
\end_layout
\end_inset
, the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
files can be stored offline.
\end_layout
\begin_layout Itemize
Move all
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
files outside of the web server's root directory.
The
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
integration can find these files anywhere on the server.
They do not need to live in a place where they can be downloaded by web
browsers.
\end_layout
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}{}
\end_layout
\end_inset
stores report designs inside
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
files.
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}{}
\end_layout
\end_inset
uses
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
to create a
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
file from the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
file.
As an analogy, the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
file is like source code and the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
file is like the executable.
The database queries, which often include database table and column names,
can be viewed using any text editor.
\end_layout
\begin_layout Standard
In short, there are a number of ways reports can be run:
\end_layout
\begin_layout Itemize
Custom web interface
\end_layout
\begin_layout Itemize
Through
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperserver{}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Manually using
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Scheduled batch process
\end_layout
\begin_layout Standard
Each of these ways to run reports dictates the security mechanisms that
must be in place before the reports can go into a production environment.
\end_layout
\begin_layout Section
Title and Subtitle
\end_layout
\begin_layout Standard
All reports must have a unique title that distinguishes them from other
reports.
Reports that differ only slightly should use a subtitle to qualify the
difference.
\end_layout
\begin_layout Section
Physical Location
\end_layout
\begin_layout Standard
As reports are developed throughout the software development lifecycle,
they exist in different locations:
\end_layout
\begin_layout Itemize
Source Code Repository
\end_layout
\begin_layout Itemize
Development Environments
\end_layout
\begin_layout Itemize
Deployment Environments
\end_layout
\begin_layout Subsection
Source Code Repository
\end_layout
\begin_layout Standard
When working on an existing report, or creating a new report, the report
must have a home that is not on a development machine.
Each report should have a known, relative path within a reports section
in a source code repository.
The repository must contain the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
files, images, styles, templates, and required subreports.
The
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
files are a byproduct of the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
files and do not need to be stored in the repository (the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
files deployed to production should have a location in the repository that
is separate from the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrxml}
\end_layout
\end_inset
files).
\end_layout
\begin_layout Subsection
Development Environments
\end_layout
\begin_layout Standard
When working with
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
, all report developers should download the reports from the repository
to the same fully qualified path on their development machine.
For example, in Windows, the directory can be:
\end_layout
\begin_layout LyX-Code
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
windirdevreports
\end_layout
\end_inset
\end_layout
\begin_layout Standard
That directory as an
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
expression can be written in a more platform-neutral way, such as:
\end_layout
\begin_layout LyX-Code
\family typewriter
"/development/reports/"
\end_layout
\begin_layout Subsection
Deployment Environments
\end_layout
\begin_layout Standard
This is directory on the web server where the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
files reside.
For example using
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appapachetomcat{}
\end_layout
\end_inset
, the directory can be:
\end_layout
\begin_layout LyX-Code
\family typewriter
/opt/apache/tomcat/reports/
\end_layout
\begin_layout Standard
This directory is outside of the web server's web root directory, making
the file inaccessible to web browsers.
\end_layout
\begin_layout Standard
Any directory outside of web server's installation directory is acceptable
as well, even preferable.
The only restriction is that the account that runs the web server must
be granted sufficient rights to read the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjasper}
\end_layout
\end_inset
files.
\end_layout
\begin_layout Section
Parameters
\end_layout
\begin_layout Standard
Most reports are for data mining and, as such, need parameters to filter
the results into manageable amounts.
The report developer needs to know the parameters, including the following:
\end_layout
\begin_layout Itemize
\series bold
Name.
\series default
How the parameter is referenced in the report.
\end_layout
\begin_layout Itemize
\series bold
Label.
\series default
A description of the parameter shown to the end user.
\end_layout
\begin_layout Itemize
\series bold
Type.
\series default
The parameter's data type (string, date, number, list, etc.).
\end_layout
\begin_layout Itemize
\series bold
Widget.
\series default
The visual interface for the end user (checkbox, radio button, text field,
etc.).
\end_layout
\begin_layout Standard
The parameters section should also include default values for parameters,
if applicable.
\end_layout
\begin_layout Section
Output Format
\end_layout
\begin_layout Standard
The
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
API supports the following output formats:
\end_layout
\begin_layout Itemize
Adobe Portable Document Format (PDF)
\end_layout
\begin_layout Itemize
Comma Separated Value (CSV)
\end_layout
\begin_layout Itemize
HTML
\end_layout
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
Excel
\end_layout
\begin_layout Subsection
PDF Files
\end_layout
\begin_layout Standard
The advantage of producing PDF files is that the result is virtually guaranteed
to look exactly the same regardless of the computer hardware or operating
system being used to view the report.
A PDF on a Macintosh running the latest version of Mac OS looks the same
as when viewing it on an Intel-based computer with the K Desktop Environment
(KDE) on top.
The biggest disadvantage to PDF files is that tabular data cannot be sorted:
the PDF must be regenerated with a new sort order, which involves programming
effort.
\end_layout
\begin_layout Subsection
Comma-Separated Value
\end_layout
\begin_layout Standard
The only disadvantage to CSV format was that, except for extremely simple
tabular reports, it meant maintaining two copies of the report: one for
CSV and one for any other output format.
This is because
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
, prior to version 4.0.0, had no easy way to collapse a complex, multi-line
layout into a single line.
The
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
4.0.0 release provides a mechanism that solves this problem.
\end_layout
\begin_layout Subsection
HTML
\end_layout
\begin_layout Standard
Exporting the report as HTML sounds simple enough, but the problem is that
the report---by default---is not exported as an HTML fragment, it is exported
as an entire HTML document.
If you want to embed the HTML within an existing web page, you have to
extract the HTML that represents the report content, while leaving the
rest of the mark-up behind (or watch the web framework render the content
useless).
\emph on
Caveat emptor!
\end_layout
\begin_layout Subsection
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
Excel
\end_layout
\begin_layout Standard
People confuse the business need for creating reports in ``Excel format''
(that is, a proprietary file format that only the software from a specific
vendor's software suite can read)
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
LibreOffice, OpenOffice, Google Documents, and other software can read spreadshe
ets created in
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
Excel, but not perfectly.
This will change as more people use open, interoperable file formats.
\end_layout
\end_inset
with the business need for creating reports that can be read by spreadsheet
programs, such as
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
Excel.
A report generated in ``Excel format'' can only be loaded by
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
Excel; whereas, a report generated in CSV format can be read by
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
Excel and all the other spreadsheet software in the world.
Business users think of solutions in terms of the technology that they
know and understand.
It is the senior developer, or team lead, who must shoulder the responsibility
of interpreting requirements that provide the most flexible solution and
still meet business needs.
\end_layout
\begin_layout Section
Query Statement
\end_layout
\begin_layout Standard
Indicate where the report's query can be found (do not embed the query in
the SRS as that would lead to duplication of maintenance effort; a hyperlink
or fully qualified path can suffice).
For complex queries, describe their algorithm in this section.
\end_layout
\begin_layout Section
Data Columns
\end_layout
\begin_layout Standard
Add a table to the SRS that defines the columns returned by the query.
The table should include the column's name, data type, and a brief description.
\end_layout
\begin_layout Standard
Take the time to create a consistent column naming scheme.
Use database views or functions to hide inconsistencies that may be present
in tables.
This will reduce the amount of time spent searching for columns and make
it easier for new developers to understand the system.
Better still, ensure the column names on the tables are always consistent.
As this is not always feasible nor practical, consider creating database
views (or functions) that hide the inconsistencies.
\end_layout
\begin_layout Section
Design
\end_layout
\begin_layout Standard
Specify how the report should look: reference standard layout, create a
pencil sketch, use a spreadsheet, or create a table in a word processor.
This is the clearest way to communicate to developers: show them the desired
final result.
If the report is not a simple columnar report, an example that shows the
layout, such as
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Example-Report-Design-Mock-up"
\end_inset
, is essential.
\end_layout
\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Example-Report-Design-Mock-up"
\end_inset
Example Report Design Mock-up
\end_layout
\end_inset
\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="4">
<features>
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
rowcolor{tableheader}
\backslash
toprule{}
\end_layout
\end_inset
\series bold
Month
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Day
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Temperature (°C)
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Average (°C)
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
midrule{}
\end_layout
\end_inset
November
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
30
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
12
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
31
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
15.5
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
December
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
10
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
2
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
8.3
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
11.45
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
tabularnewline
\backslash
bottomrule%
\end_layout
\end_inset
\end_layout
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Section
Variations
\end_layout
\begin_layout Standard
Describe all variations on the report.
Discuss column order, column sorting, different ways to group the data,
and so forth.
\end_layout
\begin_layout Section
Test Cases
\end_layout
\begin_layout Standard
Track how each report can be tested.
Depending on the database complexity, creating test cases can be quite
time consuming.
Use the test case section of the document to indicate what test inputs
to use.
Describe the expected output in this section too, if you feel it will be
helpful.
Describing the expected output is not always necessary as testers know
what they are expecting to see in the report.
\end_layout
\begin_layout Section
Summary
\end_layout
\begin_layout Standard
Ray Ozzie,
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
corpmicrosoft{}
\end_layout
\end_inset
's Chief Software Architect, was absolutely correct in stating that additional
system complexity causes developers no end of grief, because computers
function most efficiently with consistency, not exceptions.
Special cases and irregularities introduce confusion; whereas, general
cases and regularity make software development relatively straightforward.
Business requirements takes a distant view of reports, that is, the idea
is to see if specific reports are, in fact, variations on the same report.
Reports that are merely a variation on one another do not warrant creating
a separate report file and query, but are best parameterized.
Avoiding duplication at this level will greatly simplify the reports, making
them easier to maintain over time.
\end_layout
\end_body
\end_document