\documentclass[12pt,fleqn,a4paper]{report}
\usepackage[english]{babel}
\usepackage{amsfonts}
\usepackage{latexsym}
\usepackage{xspace}
\usepackage{epsfig}
\usepackage{psfrag}
\usepackage{graphicx}
\usepackage{verbatim}

\textheight	680pt
\textwidth	460pt
\topmargin	-40pt
\oddsidemargin	  5pt
\evensidemargin	  5pt
\parindent	  0pt

\begin{document}
\begin{titlepage}
\centerline{\large PS Software-Engineering}
\vspace{0.5cm}
\hspace {2.3cm}
SE-003-2000
\hspace{5.2cm}
\today

\vspace{2cm}
\centerline{\Large\bf Archaeological Data System - ADS}
\vspace{0.2cm}
\centerline{\Large\bf }

\vspace{1cm}
\centerline{\bf Report}
\centerline{\bf }

\vspace {3cm}
\vspace {1cm}
\centerline{Academic Supervisor Mag. Dipl.-Ing. Schwaiger Roland}

\vspace{1cm}
\centerline{\large Department of Computer Science}
\vspace{0.2cm}
\centerline{\large University of Salzburg}

\vspace{5.5cm}
Correspondence to: \\
\centerline{Universit\"{a}t Salzburg} \\
\centerline{Institut f\"{u}r Computerwissenschaften und Systemanalyse} \\
\centerline{Jakob--Haringer--Stra\ss e 2} \\
\centerline{A--5020 Salzburg} \\
\centerline{Austria}

\clearpage
\end{titlepage}

\title{\Large\bf Archaeological Data System - ADS}

\date{}

\maketitle

\begin{abstract}
{\sl This document deals with the development of a software-system with the
working title ''Archaeological Data System - ADS'' for entering, administrating
and presenting archaeological data via the internet.}
\end{abstract}

\tableofcontents

\chapter{Requirements Definition}
Under "requirements definition" we understand the development of contract between our anonymous customer and
us, the SE AG. This contract defines exactly, what the software system should be able to do and which premises
are valid for the realization.\newline
Since there is no exact definition for "requirements definition" we follow the ANSI/IEEE Guide to Software
Requirements Specification [ANSI 830 - 1984] and use the following structure for the requirements definition:
\begin{enumerate}
\item Initial Situation and Objective Target
\item System Environment
\item User Interfaces
\item Functional Requests
\item Non-Functional Requests
\item Error Handling
\item Documentation Requirements
\item Acceptance Criteria
\item Glossary and Index
\end{enumerate}
Before the contract between our customer and us can be established, the requirements definition has to be proofed of
completeness and correctness and the customer's demands have to be verified whether they can be realized technically
and economically. Therefore it is necessary to perform a risk analysis (see Section \ref{risk_analysis} on page %%@
\pageref{risk_analysis}).


\section{Initial Situation and Objective Target}
This section aims at clarifying topics such as our customer's wishes
and requirements concerning the software, it shall give restrictions what the
software is not to do as well as point out questions which are to be discussed
with our customer.
\bigskip
\\
As R. Yeh and P. Zave describe \cite{requirements1}, a great deal of time and
money is invested in maintenance of a software-product. To reduce this in order
to be more productive as you can concentrate on other projects, a very
important part of software-developement is to specify exactly the system's
requirements.\\
Yeh and Zave also mention 3 major steps which should be persued during this
phase of the software-project:

\begin{enumerate}
\item \textit{Problem identification:} One shall identify and describe the
needs of a system for certain purposes;
\item \textit{Problem understanding:} Collect and analyze information about the
system and its environment, as well as their interaction;
\item \textit{Problem specification:} Describe the behavior of the system.
\end{enumerate}

This section is the product of these 3 steps.

\subsection{Introduction}
Our company was engaged to develop a software-system with the working title
''Archaeological Data System - ADS'' which first of all shall:

\begin{itemize}
\item Provide an interface via the world-wide-web enabling our customer to
enter archaeological data such as tombs, settlements or artefacts into a
central database.
\item Enable third parties to query the database for information via the
world-wide-web.
\item Present the data also via a virtual museum.
\end{itemize}

We are responsible for the design and implementation of this system including
the following points:

\begin{itemize}
\item Web-front-end to manipulate and display data.
\item The design and implementation of the database itself.
\item Maintain these services.
\item Host the database on a server or at least administrate this work.
\end{itemize}

\subsection{General Overview}
As the database shall be accessible via a standard web-browser, we will not
develop an independent program which could connect to the database for
example via TCP/IP. Just the web-frontend for web-browsers will be designed
and implemented.\bigskip

Our Customer has no experience with a similar software, so we have to organize
seminars to teach the customer how to operate the system and additionally write a documentation manual for
the software. This is necessary because once ADS is in action the customer himself is responsible for
the system. We only will act as ASP (Application Service Provider) then.\bigskip

There are no limitations in the financial capital we have for this project. In
January 2001 the Inception- and Elaboration-Phase of the project should be finished and maybe we can present
our customer a prototype.

\subsection{Database}
Currently there are 4000 records to enter into the database. A record will consist of approximately
20 attributes and can also contain pictures, sketches, movies and sounds. The expected annual
growth of data is about 400 records at all (400 pics, 400 sketches, 10 movies and several
sound-samples). The multimedia-files have to be uploaded thru our web-interface. These files will not be stored into %%@
the database, but rather using the filesystem. The database will only store the path to the respective %%@
files.\bigskip

The attributes for the different fields can be found in the next chapter.\bigskip

To search in the database, our web-frontend will provide a search-screen. There will be three kinds
of queries:
\begin{description}
\item [Simple query:] Just enter a keyword and all the attributes will be compared to it.
\item [Extended query:] One can specify, which data certain attributes should contain and connect all the
search-options by logical operators.
\item [Query in the museum:] The visitor can search for special items in the museum.
\end{description}
The data collectors can specify certain attributes of a record, the visitor cannot see when searching in
the database. He can also make whole records invisible for the visitors.\bigskip

As the customer wishes the option to have several virtual museums at once, one of the records attributes will
propably be, to which virtual museum a specific object belongs to.

\subsection{Entering Data}
There are two main groups who can enter data into the database:
\begin{enumerate}
\item Data collectors
\item Scientific data collectors
\end{enumerate}
Members of the first group will enter general data concerning the
archaeological object such as the place where it was found, while members of
the second group will add additional information such as interpretations and
publications concerning this object.
\bigskip
\\
To address all questions which have to do with "Who has the right to do what in the database?" a
database-access-system has to be developed. It should enable the customer to organize the users of the
software-system in groups and equip them with certain rights (read, write, modify).\newline
So ADS will provide a user-management such as known from UNIX. There will be four groups so far:
\begin{description}
\item[Data collectors:] They can enter and manipulate general data concerning the
archaeological objects. They also can define relationships between different
types of data or specific records. Data collectors also can edit the virtual
museum where the objects are to be presented.
\item[Scientific data collectors:] They can also enter and manipulate data (even more specific one, such as
publications concerning the archaeological objects). Again they have the option
of defining relationships as mentioned before as well as editing the virtual
museum. So this group is something like an extension of the data collectors.
\item[Visitors:] They will just have the option to query the database for
information as well as to walk through the virtual museum.
\item[Administrators:] The administrators will be able to do anything they want within the system, so
they have the ability to maintain and repair small but urgent concerns, perhaps via the internet.
\end{description}
In the design of ADS we will keep an eye on the ability of adding new groups or changing groups in
future versions.

\subsection{Virtual Museum}
The software-system shall include a virtual museum where the visitors can walk
through and zoom into descriptions of archaeological objects and artefacts. The
museum shall not host all the data collected as the customer wants to perform
special exhibitions on current topics.\newline
There is no need to model the museum with 3D-graphics. Nevertheless, we have several options:
\begin{itemize}
\item Show photography-like pictures of the rooms, move within the museum by
clicking on arrows or signs.
\item Present the museum animated (via tools such as Quicktime, Flash,
Shockwave, etc.)
\item Just show a clickable room-map.
\item Others.
\end{itemize}
At this point we want to remind the customer of the fact that the virtual museum will be accessed via the
internet and as the majority of visitors will have low-speed connections, they will not be able to fully
enjoy the museum if there is too much (graphical) data to be transferred.\bigskip

The museum will have three floors, each of which consist of about ten
rooms. In each room there are several showcases which contain archeological artefacts.
The data collectors have the ability to design the museums as they like (so the scientific data
collectors also have). And of course the administrator can also manipulate the museums.\newline
For designing museums, it will be best to either offer a given set of different showcases, frames and boards
to choose from or to give a list, where one can choose which entries of the data-record will be
shown.\bigskip

The museums are usually used for special exhibitions, so there will not be all the items from the
database in the museum. The visitors have the ability to search here for
archeoligical artefacts. As a result they will get a discritpion how to get to the desired item
in the museum. If one selects a item in a showcase he is given the available data from the database.

\subsection{Additional Notes}
The customer wants to produce represantative CDs as well as catalogues of
the virtual museum and its exhibitions. These CDs will only contain the museum
itself (accesible thru a web-browser) and the corresponding extract from the database.
The customer himself is responsible for the production of this CD. So we will add a feature
which automatically copys the museum-data in a certain directory, so that he can burn the
contents of this directory on a CD-R. An equivalent feature will exist to create the catalogue.\bigskip

Our management demands the use of XML in order to be as platform-independent
as possible.



\section{System Environment}

\subsection{Hardware}
As mentioned above, ADS will be hosted by our company. We will be responsible for readiness for use and
maintenance of the system and also accessibility via the internet. Therefore we need a web-server, on which we run
ADS. Further we need a database-server, to implement the database for ADS. We shall use the latest hardware
from a well-known and reliable vendor.\newline
All the ADS-user needs, is a computer with connection to the internet (e.g. via modem)
\subsection{Software}
For our servers (web and database) we need a reliable and stable operating system (such as Solaris, HP-UX,
Linux) and web- and database-server-software to run under this OS.\newline
The demand of software for the ADS-users is very small. Only an OS and a web-browser is required.
\subsection{Data}
The database will initially contain about 4000 records (each has about 20 attributes) of archeological data.
Every year there will be about 400 new records to enter the database. Since the customer himself is responsible
to fill the database we don't need to know anymore.
\subsection{Users}
The system distinguishes between four user-groups. Three active groups (data collectors, scientific data
collectors and administrators) who can change the database and one passive group (visitors) who can only query
the database. The visitors will be the ones accessing ADS most of the time (maybe 50-500 visitors per day), while
(scientific) data collectors will use it approximately twice or three times per day (400 new entries per year
plus manipulations of existing data). The administrator is expected to work very few with the system.



\section{User Interfaces}
\textit{This section will come up within the next assignment.}



\section{Functional Requests}
The functional requests in this section are formulated using the formal language which is systematically
described thru the Backus-Naur-Form as the following:
\begin{itemize}
\item $<$Request$>$ ::= $<$Request Name$>$: $<$Request Text$>$. Request Type: $<$Request Type$>$. Priority: %%@
$<$Priority$>$.
Reason: $<$Reason$>$
\item $<$Request Name$>$ ::= $<$Text$>$
\item $<$Request Type$>$ ::= HAVE TO$\vert$SHOULD$\vert$MUST NOT
\item $<$Priority$>$ ::= 1$\vert$2$\vert$3$\vert$4$\vert$5$\vert$6$\vert$7$\vert$8$\vert$9$\vert$10
\item $<$Reason$>$ ::= $<$Text$>$
\item $<$Text$>$ ::= $<$Character$>$$<$Text$>$$\vert$$<$Character$>$
\item $<$Character$>$ ::= %%@
a$\vert$...$\vert$z$\vert$A$\vert$...$\vert$Z$\vert$0$\vert$...$\vert$9$\vert$"$\vert$.$\vert$...$\vert$;
\end{itemize}

Priorities are ranked 1 for highest and 10 for lowest priority.
\subsection{Database}
\begin{itemize}
\item DB1: The database has to be able to handle the initial 4000 records plus 400 new records per year over
several decades (every record consists of about 20 attributes, containing text and maybe multimedia-files)
\item Priority: 1
\item Reason: This is a crucial part of the software-system.
\bigskip
\item DB2: Individual attributes of the data-records have to be lockable and whole data-records have to be hideable.
\item Priority: 2
\item Reason: Some attributes as well as whole records must not be search-/viewable by the visitors.
\bigskip
\item DB3: The collected data has to be editable.
\item Priority: 1
\item Reason: One should have the possibility to edit already collected data in order to add or correct
informations.
\bigskip
\item DB4: The System has to distinguish between different user-groups.
\item Priority: 1
\item Reason: This is necessary to deal with the rights the different users have.
\bigskip
\item DB5: There has to be a group for each of the following: administrators, data collectors, scientific
data collectors and visitors.
\item Priority: 1
\item Reason: The administrators are necessary to maintain and repair urgent concerns. The other three groups
are demanded by the customer.
\bigskip
\item DB6: The group-management has to be extendable.
\item Priority: 4
\item Reason: For future releases or updates this can be very useful and time-saving.
\bigskip
\item DB7: An artefact record will contain the following attributes
	\begin{itemize}
		\item inventory-number
		\item name
		\item category
		\item scientific text
		\item size
		\item material
		\item the name of the person who found the artefact
		\item picture
		\item video
		\item sound
	\end{itemize}
\item Priority: 1
\item Reason: This is are the essential attributes demanded by the customer.
\bigskip
\item DB8: A grave-record will contain the following attributes
	\begin{itemize}
		\item gps-data
		\item gis-data
		\item scientific text
		\item the name of the person who found the grave
		\item picture
		\item video
		\item sound
	\end{itemize}
\item Priority: 1
\item Reason: This is are the essential attributes demanded by the customer.
\bigskip
\item DB8: A settlement-record will contain the following attributes
	\begin{itemize}
		\item gps-data
		\item gis-data
		\item scientific text
		\item the name of the person who found the settlement
		\item picture
		\item video
		\item sound
	\end{itemize}
\item Priority: 1
\item Reason: This is are the essential attributes demanded by the customer.
\bigskip
\item DB9: There will be a 1..n relationship between graves and artefacts. Thus, n artefacts can be associated with %%@
a grave.
\item Priority: 1
\item Reason: It is essential to link graves to artefacts.
\bigskip
\item DB9: There will be a 1..n relationship between settlements and artefacts. Thus, n artefacts can be associated %%@
with a settlement.
\item Priority: 1
\item Reason: It is essential to link settlements to artefacts.

\end{itemize}

\subsection{Web-Frontend}
\begin{itemize}
\item WF1: There has to be a seperate section for the (scientific) data collectors which has to be protected by a %%@
password system.
\item Priority: 1
\item Reason: The section where the (scientific) data collectors can edit the database has to be seperated and %%@
protected from the
visitors.
\bigskip
\item WF2: The (scientific) data collectors have to be able to enter data in form of text into the databank, as well %%@
as upload images, audio- and videofiles.
\item Priority: 1
\item Reason: One of the crucial functions of the software-system is to allow the (scientific) data collectors to %%@
update
the database via the web-frontend.
\bigskip
\item WF3: There has to be a simple text-search function, which searches all the records and their attributes which %%@
contain text (except hidden records and locked attributes) for the entered search word.
\item Priority: 1
\item Reason: The visitor has to be able to search the database in a simple way.
\bigskip
\item WF4: There has to be an advanced search function, which searches for specific attributes (except hidden %%@
records and locked attributes). The entries have to be connected with logical operators.
\item Priority: 3
\item Reason: The advanced visitor has to be able to search the database more specifically.
\bigskip
\item WF5: There has to be a searchable knowledge tree which leads to the items.
\item Priority: 5
\item Reason: The visitor should be able to start his search in a general field of interest and specify his search %%@
as he moves up the knowledge tree.
\bigskip
\item WF6: The web-frontend must not be based on additional plug-ins for web-browsers.
\item Priority: 1
\item Every visitor shall have the same access to our system without downloading and installing plug-ins.
\end{itemize}

\subsection{Virtual Museum}
\begin{itemize}
\item VM1: There has to be a Virtual Museum with initially 3 floors and 10 rooms per floor (there are several
showcases in a room, where certain artefacts from the database are on display).
\item Priority: 1
\item Reason: This is a crucial part of the software-system. The customer has to be able to display certain %%@
artefacts.
\bigskip
\item VM2: The visitors have to be able to browse through the museum.
\item Priority: 1
\item Reason: The visitors must be able to view the items that are on display in the showcases.
\item VM3: The Virtual Museum has to be expandable and editable.
\item Priority: 3
\item Reason: The customer wants to edit the layout of the rooms and showcases as well as add additional floors to %%@
the museum.
\bigskip
\item VM4: There has to be a search function in the virtual museum.
\item Priority: 3
\item Reason: The visitor might like have a description how to get to the object of his interest.
\bigskip
\item VM5: The museum has to be able to host an exhibition concerning a special topic.
\item Priority: 4
\item Reason: This is a feature our customer demands.
\bigskip
\item VM6: The museum has to be depicted by sophisticated graphics.
\item Priority: 7
\item Reason: Visitors should get an comfortable and eye-catching surface.
\bigskip
\item VM7: The (scientific) data collectors has to be able to create a representing CD-ROMs and printed
catalogues of a special exhibition in the virtual museum.
\item Priority: 2
\item Reason: This is a feature our customer demands.
\end{itemize}


\section{Non-Functional Requests}
Factors such as the reaction time of our software-system depend very much on third-party's performances or
other factors (e.g. internet-providers, rush-hours on the data-highway). In combination with the fact that
our company uses the latest hardware and of course competent and efficient programming, it therefore makes
little sense to give exact statements such as "The database gives an answer within 2.5 seconds".
If the customer wants the final product to be faster than the prototype, we will try to do some improvements
of performance if possible.\bigskip

The stability of the system shall be reached by using high-quality hardware and a reliable operating system.
Of course stability and usability also depends on the quality of our product.\bigskip

The use of XML combined with the fact that no special plug-ins but just a plain web-browser are going to be
used grant high portability. This is necessary in order to offer features such as producing CDs or
catalogues.\\
XML will be an intermediary layer in the system, enabling us to publish content in HTML, PDF, or what ever format %%@
wished for by the customer.


\section{Error Handling}

\subsection{Database}
\begin{itemize}
\item DB-ERR1: The database doesn't react to queries from the web-frontend.
\item Cause: The DB-server-daemon failed or isn't loaded.
\item Solution: Generate an error message and inform the technical administrator.
\bigskip
\item DB-ERR2: A query doesn't return any results although the desired information is definitely stored in
the database.
\item Cause: This might be due to malformed DB-queries.
\item Solution: Our company has to go thru these routines and fix the error.
\bigskip
\item DB-ERR3: The database gives too much information (e.g. shows records or attributes which are actually
locked).
\item Cause: This might be due to malformed DB-queries.
\item Solution: Our company has to go thru these routines and fix the error.
\bigskip
\item DB-ERR4: The (scientific) data collectors can't add or edit any information.
\item Cause: The user is assigned to a wrong group or the rights of that group are not set correctly. The
file-system  gives a write-permission-error. The system resources are too low (e.g. not enough free disk-space).
\item Solutions: The administrator has to assign the user to the right group or set the group rights
correctly. The administrator has to check and correct the environment of the system.
\end{itemize} 

\subsection{Web-Frontend}
\begin{itemize}
\item WF-ERR1: The web-frontend does not load.
\item Cause: The hardware failed. The web-server-daemon failed. Third-party failure (such as the user's
provider can't connect to our system).
\item Solution: Contact the technical administrator.
\bigskip
\item WF-ERR2: The web-frontend does not load properly. Parts of the page are missing.
\item Cause: Files are missing or not set up correctly.
\item Solution: Contact the webmaster.
\end{itemize}

\subsection{Virtual Museum}
\begin{itemize}
\item VM-ERR1: The Virtual Museum (or single parts of it) does not load.
\item Cause: The server is down. Several files are missing.
\item Solution: Contact the technical administrator.
\end{itemize}


\section{Documentation Requirements}
As our customer has no previous experience with similar software-systems and wishes to be independent after
finishing the project, the product manual has to contain detailed instructions dealing with the following
issues:
\begin{itemize}
\item Modification of the data-access-system. Explains how to
\begin{itemize}
\item change the rights of certain groups
\item add users and groups
\item change the group of a user
\end{itemize}
\item Modification of the Virtual Museum. Explains how to
\begin{itemize}
\item add floors, rooms, showcases and artefacts to the museum
\item equip rooms and showcases with topics
\item change the layout of rooms and showcases
\end{itemize}
\item Update the database. Explains how to
\begin{itemize}
\item enter data-records into the database
\item upload files into the database
\end{itemize} 
\end{itemize} 

Because ADS isn't a commercial software-product and the customer didn't demand it, there's no use to make a
printed handbook. The documentation will be only available as a Software-Document (such as Postscript, Adobe
Acrobat, HTML, ...) from which one can make a hardcopy.

\section{Acceptance Criteria}
The most important criteria which have to be fulfilled so that our customer accepts our product are
listed in the sections above. If we can deliver the product in time while implementing the reqired features,
this should lead to a positive acceptance.

\section{Glossary and Index}
\begin{description}
\item[Data-Access-System:] An administrative concept to handle the rights of groups of users, defining their rights %%@
to read/write/modify data.
\item[Knowledge Tree:] A search method which starts with a general topic. The user can then choose between several %%@
branches and in doing so specify the topic he is interested in.
\item[Router:] A device use to interconnect two or more LAN's together, each of which operates with a
different medium access control method - also known as a gateway or intermediate system.
\item[TCP/IP:] The complete suite of protocols including IP, TCP and the associated application protocols.
\end{description}

\section{Risk Analysis}
As an importanat part of the cost-benefit calculations we're performing a risk analysis for ADS. According to
E. Yourdon \cite{mod_struct_anal} risk analysis should always be done, even if nobody asked for it. This is
because it can be helpful to know which things can go wrong and thereby can be the cause for a lot of problems
and additional costs.
\label{risk_analysis}
\subsection{Database}
The expected amount of data in the database is rather modest and should not be a problem for a modern
database management system. If the system should run short of storage space in the future, it will
be no problem to provide additional disk space. Hence, the risk of problems with that part of the
software-system can be classified as low.

\subsection{Web-Frontend}
The only risk connected with the web-frontend is, that the customer might not be satisfied with our design
proposals. It will be important to show him some basic layouts in an early stage, to make clear what
the customer is looking for and in doing so, avoid the risk of wasting too much time and manpower on
unnecessary design work. The technical specifications of the web-frontend should not be a problem for our
experienced developers.

\subsection{Virtual Museum}
Concerning the virtual museum, it has to be said that the customer has very loose ideas of what it should
finally look like. This might lead to problems, if the customer is not satisfied with our developer's
suggestions. To avoid the necessity of last-minute adjustments of the whole concept, this risk should be
minimized by clarifying if our proposals meet his demands.
\bigskip

Another risk lies in the fact that the museum has to be viewable without the aid of additional plug-ins.
On the one hand this might result in an increased need of time and work to find solutions for otherwise
easily solveable problems (e.g. when using Flash- or Quicktime-plug-ins), on the other hand it minimizes the
risk of compatibility problems.

\subsection{Stability}
As the system shall always be up and we are responsible for it's stability and readiness for use, this point
is quite important to ensure smooth working. We therefore should use a well-known and reliable hardware and
operating system for the servers as well as make a contract with a service-company for case that the hardware
fails. The use of XML and possible choice of SQL as the basis for database lead to a quite platform-independent
design of the core-components.

\subsection{Personnel}
As our project team is rather small, it can have a great influence on the software-development and on the
project if somebody leaves the team. If we had to recruit new personnel this could cost a lot of time and
money.\newline
On the other side the facts, that within our team the project-leader changes with every new assignment and
every team member has to work out an individual solution for the current assignment, have the effect that
every team-member is on the same know-how-level. So, if one team-member will be disabled for just a little
time, this will not handicap the whole team. But if three or more members drop out for the same time, the
project is endangered.

\subsection{Hardware}
The only limitation to the used hardware is it's stability. If it turns out that there are not enough
resources, such problems can easily be solved by adding more resources. As we have no limitations concerning
financial investments, the hardware shouldn't be a problem.

\subsection{Miscellaneous}
Concerning some risks mentioned by E. Yourdon \cite{mod_struct_anal} and S. Vollmann \cite{aufwandschaetzung} the %%@
following can be said:
\begin{itemize}
\item If there is much traffic on the internet, the response time may drop down. Since we can do
nothing about this, we have to accept the risk of partially slow connections.
\item In case of electric power breakdown, our power generator will start up, to ensure power supply for our
servers. Customers won't recognice that at all.
\item It remains negotiated with our customer who shall be held responsible for possible loss of data.
Nevertheless, such a risk shall be minimized by making regular backups.
\item It is the responsibility of our management to evaluate our cutomer's credit-worthiness.
\end{itemize}

%USE CASE DOCUMENTATION

\chapter{Use Case Documentation}

\section{Introduction}

As \cite{use_case1} states, when defining primary uses cases, it is not needed to capture "every detail of the use %%@
cases". Thus, use cases are used primarily to capture the high level user-functional requirements of a system (cf. %%@
\cite{use_case2})\\
Keeping this definition in mind, we design our use-case-model not primarily as a design-concept, but rather as an %%@
auxiliary means for communicating with the customer. The primary use-cases reflect the basic functionality of the %%@
ADS. Of course, the model is abstract and these primary use-case are constituted by a lot of sub-use-cases (e.g. %%@
Administrate is a very abstract use-case, consituting of CreateBackup, ManageRights, etc). 

\section{System Description}

%\subsubsection{System Name}

%\subsubsection{Risk Factors}

\subsection{System-Level Use Case Diagram}
\vspace{2ex}
see Figure \ref{uc_system} on page \pageref{uc_system}
\begin{figure}
\begin{center}
\includegraphics {diagram1.eps}
\end{center}
\caption{\label{uc_system}System-Level Use Case Diagram}
\end{figure}


\subsection{Actors}
\begin{itemize}
\item InternetUser\bigskip\\
The InternetUser is interested in viewing the data and
museums. He ist the one visiting the webpage of the
ADS and using the ADS for display-purposes
\item Designer\bigskip\\
A Designer creates Virtual Museums. He can arrange floors, room and vitrinas, but is not necessarily able to enter %%@
data. Furthermore, a Designer is able to create publications, such as a CD-Rom or a catalogue.
\item DataCollector\bigskip\\
{
A DataCollector is able to enter data concerning
artefacts, graves and settlements into the system.
DataCollectors (as they are generalized by Designers) can create and modify virtual museums.
}

\item Scientific DataCollector\bigskip\\
{
 A Scientific DataCollector is able to enter data
concerning artefacts, graves and settlements.
Furthermore, a Scientific DataCollector is able to add
scientific documentation. Scientific Data Collectors (as they can generalized by DataCollectors) can create and %%@
modify Virtual Museums.\\
For reference purposes the Use-Case: Enter Scientific Data has been added for this actor - see Figure \ref{uc_scd} %%@
on page \pageref{uc_scd})}
\item Administrator\bigskip\\
An administrator has all the rights of the other
groups, i.e. he  is able to enter data, scientific, etc.
Furthermore he has the privilege to edit rights and
groups.

\end{itemize}
\begin{figure}
\begin{center}
\includegraphics {diagram2.eps}
\end{center}
\caption{\label{uc_scd}Actor: Scientific Data Collector, Use Case: Enter Scientific Data}
\end{figure}




\subsection{Use Cases}
The use-cases will be explained in more detail in section \ref{use_cases_detail}.
\begin{itemize}
\item Authenticate
\item View Data
\item Enter Data
\item Enter Scientific Data
\item Search
\item View Museum
\item Edit Museum
\item CreatePublications
\item Administrate
\end{itemize}

\begin{comment}
Or you could just list the actors and use cases in text.
\end{comment}

%\subsubsection{Architecture Diagram}

\begin{comment}
Include a description of the interfaces as well. These could be on the diagram,
or listed in text.
\end{comment}

%\subsubsection{Subsystem Descriptions}

\begin{comment}
Include a brief description of each subsystem.
\end{comment}


\section{Detailed Use Case Description: Primary Use Cases}
\label{use_cases_detail}



\subsection{Use Case: Authenticate}
Authenticate is used to identify a user and associate him with a group with more rights than an InternetUser, i.e. %%@
DataCollector, Scientific DataCollector, Administrator. 

\subsubsection{Actors}
\begin{itemize}

\item DataCollector
\item Scientific DataCollector
\item Administrator

\end{itemize}


\subsubsection{Priority}
Priority: 3\\
Reason: The authentication can be implemented after other use-ases have been done.

%\subsubsection{Status}

\begin{comment}
At what point are we in developing this use case?
\end{comment}

\subsubsection{Preconditions}
\begin{itemize}
	\item ''Login'' pressed
\end{itemize}
\subsubsection{Postconditions}
\begin{itemize}
	\item The respective actor is authenticated as DataCollector, Scientific DataCollector or Administrator or %%@
authentication fails.
\end{itemize}

\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
none

\subsubsection{Flow of Events}
\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects ''Login''
\item Actor supplies Login-name
\item Actor supplies Password
\item Login-Name and Password match
\item User-Data (and associated group) is retrieved from Data-Base
\item User is logged in and granted rights according to his group-association
\end{enumerate}
\vspace{2ex}
\underline{Secondary Scenario}
\begin{enumerate} 
\item Actor selects ''Login''
\item Actor supplies Login-name
\item Actor supplies Password
\item Login-Name and Password do not match
\item System displays an error-message
\item User is not logged in
\end{enumerate}

%\subsubsection{Activity Diagram}
\begin{comment}
An activity diagram of the flow of events, or some significant or complex part
of the flow of events.
\end{comment}

\subsubsection{User Interface}
\begin{itemize}
\item Input-field for login-name
\item Input-field for password (hidden input!)
\item submit-button
\end{itemize} 
\begin{comment}
For systems that interface with people, include a description of the user interface,
possibly using storyboards.
\end{comment}

%\subsubsection{Secondary Scenarios}

\begin{comment}
If alternatives and exceptions are not shown in the flow of events, scenarios
should be listed here, and a brief description may be included.
\end{comment}

%\subsubsection{Sequence Diagrams}

\begin{comment}
If you do not have separate documents for scenarios, you might include sequence
diagrams for them here.
\end{comment}

\subsubsection{Subordinate Use Cases}
none
\begin{comment}
If the use case has subordinate use cases, show them here. Or you could include
a use case diagram for the subordinate use case. Or both. Also tell what subsystem
is responsible for this subordinate use case.
\end{comment}

%\subsubsection{View of Participating Classes}

\begin{comment}
A collaboration showing all the classes whose objects interact to implement
this use case. You also can show interfaces to the use case here and which of
the classes implement the interfaces.
\end{comment}

%\subsubsection{Other Artifacts}

\begin{comment}
This can include references to the subsystem the use case belongs to, an analysis
model, adesign model, code, or test plans.
\end{comment}

\subsubsection{Other Requirements}
none
\vspace{2ex}

\subsection{Use Case: Enter Data}

Enter Data is used for submitting data to the webfrontend as well as editing data that was entered previously. 


\subsubsection{Actors}
\begin{itemize}
\item Data Collectors (and thus also Scientific DataCollectors as they are generalized by DataCollectors, and %%@
Administrators as they are generalized by Scientific DataCollectors) \footnote{In the description of further use %%@
cases, if not stated otherwise, it will be presumed that if an actor is generalizes by another actor, the former %%@
inherits the rights of the latter. (Cf. Figure \ref{uc_system} on page \pageref{uc_system} for %%@
''generalize''-hierarchy of actors)}
\end{itemize}

\subsubsection{Priority}
Priority: 1
Reason: Entering Data is an essential part of the system.

\subsubsection{Preconditions}
\begin{itemize}
\item ''Enter Data'' is selected by an actor with the rights to do so
\end{itemize}

\subsubsection{Postconditions}
\begin{itemize}
 \item Data is stored in the database or use-case fails
\end{itemize}

\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
Use Case Authentication

\subsubsection{Flow of Events}
\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects ''Enter Data''
\item Actor has the right to enter data
\item Actor enters data into user-interface
\item Actor presses submit-button
\item System submits data to the database
\item Data is stored
\item A confirmation is displayed
\end{enumerate}
\vspace{2ex}

\underline{Secondary Scenario A}
\begin{enumerate} 
\item Actor selects ''Enter Data''
\item Actor has the right to enter data
\item Actor enters data and paths to multimedia data into user-interface
\item Actor presses submit-button
\item System submits data to the database
\item System uploads multimedia files and stores them using the filesystem.  
\item Data is stored, paths to multimedia files are stored
\item A confirmation is displayed
\end{enumerate}

\vspace{2ex}
\underline{Secondary Scenario B}
\begin{enumerate} 
\item Actor selects ''Enter Data''
\item Actor selects ''Edit Data''
\item Actor has the right to edit data
\item Actor selects the entry to modify
\item System displays data entered in the database
\item Actor changes data
\item Actor presses submit
\item Data is changed in Database
\item A confirmation is displayed
\end{enumerate}


\vspace{2ex}
\underline{Secondary Scenario C}
\begin{enumerate} 
\item Actor selects ''Enter Data''
\item Actor does not have the right to enter data
\item An error message is displayed
\end{enumerate}
\vspace{2ex}


%\subsubsection{Activity Diagram}

\subsubsection{User Interface}
\begin{itemize}
\item input-fields to supply textual information for each textual attribute
\item input-fields to supply paths to multimedia-files for eacht multimedia-attribute
\item submit-button
\end{itemize}


%\subsubsection{Secondary Scenarios}

%\subsubsection{Sequence Diagrams}

\subsubsection{Subordinate Use Cases}
none

%\subsubsection{View of Participating Classes}

%\subsubsection{Other Artifacts}

\subsubsection{Other Requirements}
none

\subsection{Use Case: Enter Scientific Data}
Enter scientific data is used to supply scientific texts associated with an entry.

\subsubsection{Actors}
\begin{itemize}
\item Scientific Data Collectors
\end{itemize}

\subsubsection{Priority}
Priority: 1
Reason: Entering Data is an essential part of the system.

\subsubsection{Preconditions}
\begin{itemize}
\item ''Enter Scientific Data'' is selected by an actor with the rights to do so
\end{itemize}

\subsubsection{Postconditions}
\begin{itemize}
 \item Data is stored in the database or use-case fails
\end{itemize}

\subsubsection{Extension Points}
none
\begin{comment}
If the use case has extension points, list them here.
\end{comment}

\subsubsection{``Used'' Use Cases}
Enter Data

\subsubsection{Flow of Events}

\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects ''Enter Scientific Data''
\item Actor has the right to enter scientific data
\item Actor enters data into user-interface
\item Actor presses submit-button
\item System submits data to the database
\item Data is stored
\item A confirmation is displayed
\end{enumerate}
\vspace{2ex}


\vspace{2ex}
\underline{Secondary Scenario A}
\begin{enumerate} 
\item Actor selects ''Edit Scientific Data''
\item Actor has the right to edit data
\item Actor selects the entry to modify
\item System displays data entered in the database
\item Actor changes data
\item Actor presses submit
\item Data is changed in Database
\item A confirmation is displayed
\end{enumerate}
\vspace{2ex}


\underline{Secondary Scenario B}
\begin{enumerate} 
\item Actor selects ''Enter Scientific Data''
\item Actor does not have the right to enter scientific data
\item An error message is displayed
\end{enumerate}
\vspace{2ex}

%\subsubsection{Activity Diagram}


\subsubsection{User Interface}
\begin{itemize}
\item input-fields to supply textual information for each textual attribute
\item submit-button
\end{itemize}

%\subsubsection{Sequence Diagrams}

\subsubsection{Subordinate Use Cases}
none

%\subsubsection{View of Participating Classes}

%\subsubsection{Other Artifacts}

\subsubsection{Other Requirements}
none



\subsection{Use Case: View Data}
The actor in this use case is interested in displaying a single item.

\subsubsection{Actors}
\begin{itemize}
\item InternetUser
\end{itemize}

\subsubsection{Priority}
Priority: 1
Reason: Displaying data actually is one of the main purposes of ADS

%\subsubsection{Status}
\subsubsection{Preconditions}

\begin{itemize}
\item an item is selected by the actor (e.g. through Search or ViewMuseum)
\end{itemize}
\subsubsection{Postconditions}
\begin{itemize}
\item item-data or an error-message is displayed
\end{itemize}


\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
Authenticate

\begin{comment}
If the use case uses other use cases, list them here.
\end{comment}

\subsubsection{Flow of Events}
\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects an item
\item System checks users rights
\item Systemretrieves data fields of that item, the user is entitled to see, from the database
\item Data is displayed in appropriate from
\end{enumerate}
\vspace{2ex}

\underline{Secondary Scenario}
\begin{enumerate} 
\item Actor selects an item
\item System cannot find item in database
\item An error-message is displayed
\end{enumerate}
\vspace{2ex}

%\subsubsection{Activity Diagram}


\subsubsection{User Interface}
see storyboard

\subsubsection{Other Requirements}
none



\subsection{Use Case: View Museum}
This use case refers to the process of an actor viewing a museum. The actor is able to navigate through floors, %%@
enter rooms, look at vitrinas and select items from a vitrina for more detailled display.

\subsubsection{Actors}
\begin{itemize}
\item InternetUser
\end{itemize}

\subsubsection{Priority}
Priority: 4
Reason: Museums will be implemented after several other use-cases have been implemented.


%\subsubsection{Status}
\subsubsection{Preconditions}

\begin{itemize}
\item actor selects ''View Museum''
\end{itemize}
\subsubsection{Postconditions}
\begin{itemize}
\item Museum or an error-message is displayed
\end{itemize}

\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
View Data (and thus also Authenticate)

\subsubsection{Flow of Events}
\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor clicks on ''View Museum''
\item System checks users rights
\item System displays museum
\item Actor can naviage through the museum (i.e. floors and rooms) and/or view single items or vitrinas
\end{enumerate}
\vspace{2ex}

\underline{Secondary Scenario}
\begin{enumerate} 
\item Actor selects ''View Museum''
\item No museum is active
\item An error-message is displayed
\end{enumerate}
\vspace{2ex}

%\subsubsection{Activity Diagram}

\subsubsection{User Interface}
\begin{itemize}
\item display of museum
\item navigation
\item display of rooms
\item display of vitrinas
\item display of artefacts
\end{itemize}

\subsubsection{Other Requirements}
none


\subsection{Use Case: Edit Museum}

\subsubsection{Actors}
\begin{itemize}
\item DataCollector
\end{itemize}

\subsubsection{Priority}
Priority: 3
%\subsubsection{Status}

\subsubsection{Preconditions}

\begin{itemize}
\item ''Edit Museum'' is clicked by the actor
\item Actor has the right to edit museums
\end{itemize}
\subsubsection{Postconditions}
\begin{itemize}
\item Museum data is edited or an error-message is displayed
\end{itemize}

\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
Authenticate

\subsubsection{Flow of Events}
\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects a museum (if there are several)
\item System checks actor's rights
\item Actor has the right to edit museum
\item Museum data is displayed
\item Actor modifies data (i.e. creates/modifies rooms, vitrinas, or delete museum)
\item Actor presses ''submit''
\item System updates Museum
\end{enumerate}
\vspace{2ex}



\underline{Secondary Scenario A}
\begin{enumerate}
\item System checks actor's rights
\item Actor has the right to edit museum
\item No museum is established yet
\item System adds museum
\item Flow of events continues as from step 4. in primary scenario 
\end{enumerate}
\vspace{2ex}

\underline{Secondary Scenario B}
\begin{enumerate} 
\item Actor selects a museum (if there are several)
\item System checks actor's rights
\item Actor does not have the right to edit museum
\item An error-message is displayed
\end{enumerate}
\vspace{2ex}



%\subsubsection{Activity Diagram}

\subsubsection{User Interface}
see storyboard

\subsubsection{Subordinate Use Cases}
AddMuseum\\
N.B. This use cases will be documented in a later stage when we are dealing with use-cases in more detail.

\subsubsection{Other Requirements}
none



\subsection{Use Case: Search}

The actor searches the whole data he is entitled to see or searches a museum for specific entries. There are two %%@
kinds of searches: basic search and complex search. 


\subsubsection{Actors}
\begin{itemize}
\item InternetUser
\end{itemize}


\subsubsection{Priority}
Priority: 1\\
Reason: Searching the museum will make navigation a lot easier for the users

%\subsubsection{Status}

\subsubsection{Preconditions}
\begin{itemize}
\item Actor selects ''Search''
\end{itemize}

\subsubsection{Postconditions}

\begin{itemize}
\item System displays search results or an error-message
\end{itemize}


\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
ViewData

\subsubsection{Flow of Events}

\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects ''Search all data''
\item Actor enters query (simple or complex)
\item System checks actor's rights
\item System searches data according to user's rights
\item System displays a list of found items
\item Actor selects an item
\item System displays that item ($\rightarrow$ Use-Case: ViewData)
\end{enumerate}
\vspace{2ex}


\underline{Secondary Scenario}
\begin{enumerate} 
\item Actor is in a museum
\item Actor selects ''Search museum''
\item Actor enters query (simple or complex)
\item System checks actor's rights
\item System searches data according to user's rights
\item System displays a list of found items
\item Actor selects an item
\item System displays that item ($\rightarrow$ Use-Case: ViewData)
\end{enumerate}
\vspace{2ex}

In both of the above scenarios, at step 5. if no items are found, an appropriate message is returned.


%\subsubsection{Activity Diagram}


\subsubsection{User Interface}
\begin{itemize}
\item A possibility to choose between basic and complex search
\item Masks for entering the query for both basic and complex search
\item Display of results
\end{itemize}


%\subsubsection{Sequence Diagrams}

\subsubsection{Subordinate Use Cases}
SearchData, SearchMuseum\\
N.B. These use cases will be documented in a later stage when we are dealing with use-cases in more detail.

%\subsubsection{View of Participating Classes}

\begin{comment}
A collaboration showing all the classes whose objects interact to implement
this use case. You also can show interfaces to the use case here and which of
the classes implement the interfaces.
\end{comment}

%\subsubsection{Other Artifacts}

\subsubsection{Other Requirements}
none

\subsection{Use Case: CreatePublications}
The actor selects a museum or a part of the data in order to publish it in a catalogue or a CD-Rom.
\subsubsection{Actors}
\begin{itemize}
\item Designer 
\end{itemize}

\subsubsection{Priority}
Priority: 5\\
Reason: The creation of publications can be easily added after the main system is designed.

%\subsubsection{Status}

\subsubsection{Preconditions}
\begin{itemize}
	\item ''Publish'' pressed
\end{itemize}

\subsubsection{Extension Points}
none

\subsubsection{``Used'' Use Cases}
Authenticate

\subsubsection{Flow of Events}
\vspace{2ex}
\underline{Primary Scenario}
\begin{enumerate} 
\item Actor selects ''Publish Museum''
\item If there are several museums, the system displays a list of museums.
\item If there are several museums, actor chooses one
\item Actor chooses way of publishing
\item System publishes the data in the specified way
\end{enumerate}
\vspace{2ex}
\underline{Secondary Scenario}
\begin{enumerate} 
\item Actor selects ''Publish Data''
\item System displays entries the actor is entitled to view
\item Actor choosed data to publish
\item Actor chooses way of publishing
\item System publishes the data in the specified way
\end{enumerate}

%\subsubsection{Activity Diagram}

\subsubsection{User Interface}
see storyboard
%\subsubsection{Secondary Scenarios}

%\subsubsection{Sequence Diagrams}


\subsubsection{Subordinate Use Cases}
none yet

%\subsubsection{View of Participating Classes}

%\subsubsection{Other Artifacts}

\subsubsection{Other Requirements}
none
\vspace{2ex}


\subsection{Use Case: Administrate}

This use-case deals with the various tasks that need to be performed by an administrator, such as maintanence of the %%@
syste, creating backups, managing groups, managing rights, etc.\\It will evolve during the implementation, thus the %%@
description here is not meant to be taken as complete. 

\subsubsection{Actors}
\begin{itemize}
\item Administrator
\end{itemize}

\subsubsection{Priority}
Priority: 1\\


%\subsubsection{Status}

\begin{comment}
At what point are we in developing this use case?
\end{comment}

\subsubsection{Preconditions}
\begin{itemize}
\item Actor logs in as administrator
\end{itemize}


\subsubsection{Postconditions}
none

%\subsubsection{Extension Points}

\begin{comment}
If the use case has extension points, list them here.
\end{comment}

\subsubsection{``Used'' Use Cases}
none yet

\subsubsection{Flow of Events}
As this use-case will be made up of a lot of differen sub-ordinate use-cases a flow of event will not be given at %%@
this point.
%\subsubsection{Activity Diagram}

\begin{comment}
An activity diagram of the flow of events, or some significant or complex part
of the flow of events.
\end{comment}

\subsubsection{User Interface}
see storyboard

%\subsubsection{Sequence Diagrams}

\begin{comment}
If you do not have separate documents for scenarios, you might include sequence
diagrams for them here.
\end{comment}

\subsubsection{Subordinate Use Cases}
ManageRights, ManageGroups, CreateBackup, etc.
(This list is by no means complete!)

%\subsubsection{View of Participating Classes}

%\subsubsection{Other Artifacts}


\subsubsection{Other Requirements}
\begin{itemize}
\item login as administrator has to be secure
\end{itemize}
 





\bibliographystyle{ieeetr}
\addcontentsline{toc}{chapter}{Bibliography}
\bibliography{a3}
\end{document}
