2D1455 - Laboratory Exercise 1.

The Security Controller Requirements.

This series of exercises is designed to take you through the process of

object-oriented requirements analysis.

leading to a set of live sequence charts (LSCs). It will give you the chance to put into practise the analysis and modelling ideas you have learned on the course.

1. Getting Started

You will be developing your design solutions to this exercise as a hyper-linked set of web pages,

such as would be suitable to store on a companies intranet, allowing you to share your solution

with business colleagues.

To prepare for this lab exercise begin by carrying out the following task

1. Create a new folder for this lab exercise, you may call it something like "2D1455-lab1".
   
   
2. Within this folder, create an html file, you may call it something like "project1_catalog.html".
   This file will contain the contents page of your lab work. It will name each section, in an
   index, and contain a hyperlink to that section. Each lab exercise will be contained in a
   separate html file.
   
   
3. Add the following text to your catalog file, which includes your personal details for marking:
   
   

   2D1455 Laboratory Exercise 1
   
   Security Control System Requirements
   
   <name of lab partner 1>, <e-mail address of lab partner 1>
   <name of lab partner 2>, <e-mail address of lab partner 2>
   
   Contents

   1. Requirements Analysis
   <a href= "informal_req.html">Exercise 1.1:</a> Informal Requirements.
   <a href= "data_dictionary.html">Exercise 1.2:</a> Data Dictionary.
   <a href= "use_cases.html">Exercise 1.3:</a> Use Cases.
   <a href= "req_object_model.html">Exercise 1.4:</a> Requirements Object Model.
   

   
   
4. Since the Play-Engine is Windows based, you will need access to a graphics tool which can take a screen shot of a window and save the result as a JPEG or GIF file. Personally I use Paintshop Pro for this task, but you may find another solution. Currently I know of no other way to export the graphics from the Play-Engine.
   
   
5. You are now ready to begin the laboratory exercises.
   
   
   

1. Requirements Analysis Phase

1.1. Learning Events

1.2. Introduction to Exercise 1

1.3. The Informal End User Requirements

1.4. Marking up the Informal End-User Requirements

1.5. Creating the Data Dictionary

1.6. Creating the Use Case Model

1.7. Creating the Requirements Object Model

1.1. Learning Events

In lab exercise 1 you will learn how to:

1. identify important O-O requirements components, from an informal requirements document
2. construct a data dictionary from requirements components
3. identify actors and use cases and to compile the information into text documents
4. create a text use case
5. formalise an LSC use case from a text use case

1.2. Introduction to Exercise 1

In Exercise 1 you will carry out the requirements analysis phase of an O-O design. The aim of the requirements analysis phase is to:

• improve understanding of the problem domain - a (simple!) security control system, and its environment
• identify and clarify all the requirements posed on the security control system and add further details where necessary

We will guide you through the initial steps of each exercise part. Your task will be to continue and
complete the missing information.

Therefore you should have a clear pattern of work to follow at each stage.

1.3. The Informal End User Requirements

Your end user has asked you to produce a requirements analysis for a

computerised security control system.

The purpose of this system is to control the access to, and hence security of, a given set of offices.
(You do not yet know the actual number or organisation of the offices. This may or may not be revealed to you as an outside party!)

An entrance to an office can have have four different security levels:

1. door is always unlocked
2. door requires a card to unlock
3. door requires a card and also a code to unlock
4. door is always locked.

The security levels of an office entrance can be altered during the day.

Each employee working in the office has a card with a personal code consisting of four digits.

To open a door with security level three, the employee enters his/her card into a card reader

and types the personal code on a keypad. The time between consecutive keystrokes when typing the code

is not allowed to exceed three seconds. To enter through a door with security level two, the employee just

enters the card into a card reader.

Each entrance leading into the office consists of a door with an electronic lock, and also a card reader,

a keypad and a display on the outside, an alarm and an exit button (to open the door immediately, and for

emergency exits!) on the inside. The employee needs a card and a code to enter the office. To exit,

the employee just presses the exit button and the door is unlocked for ten seconds. If the door

remains open for more than ten seconds then the entrance alarm sounds. If it is intended that the door

remain open for more than ten seconds, then its security level must be level 1, i.e. always unlocked.

All entrances communicate directly with a central controller. This system carries out validation of

the correctness of cards and codes. The controller makes use of a database consisting of all

card numbers in use, and their corresponding personal codes. At level 3, a presented card is

valid if the presented code matches its database record, otherwise a card is valid if its number is

in use. If a presented card is valid, then the door at which the card is presented is opened for

ten seconds and the employee may enter. In the case of an invalid, or unregistered card, access

to the office is not allowed. In the case of an incorrect code, the employee presenting the card is

informed of this and must try again by reinserting the card into the card reader and retyping the

personal code. If the code is incorrectly typed in 4 times in succession then the card number is invalidated by the

central controller, and the card holder must contact the system manager to gain access.

The security control system must read its data, consisting of card numbers with their corresponding

personal codes, from a database. The database is managed with a separate management system

that is not being developed within this particular project. The system administrator is authorised

to validate card numbers, register new employees, cards and codes, to change a code if an employee wishes so, to

delete employees from the database and to change the security level of an entrance. The system

operator is also responsible for initialising the security control system, for example after a hardware repair. All the actions described

above are done using the management system.

The system must be able to recover from computer and communication failures.

If a communication between an entrance and the central controller is lost, the door

should be locked from the outside, not permitting anyone to enter without a card and a code (i.e. the security level

is set to three). However, it is possible to open the door using the exit button.

The system must be extensible to include new functions and must be easily maintainable.

1.4. Marking up the Informal End-User Requirements

To begin the requirements analysis you will markup the informal end-user requirements text

of Section 1.3. You should perform the following steps.

1. Cut and paste Section 1.3 into its own html file in your file area. You should call your document something like "informal_req.html". You may do this for example using a web browser, by taking the text from the course homepage using the browser "view source" control. (This will save you some retyping.)
   
   
2. Link the file "informal_req.html" to the hyperlink "Exercise 1: Informal Requirements" on the homepage of your project. It is now accessable from the table of contents for your project.
   
   
3. Read carefully through the document and markup every: noun (e.g. security control system, card, card number ... ), verb phrase (e.g. change code, change security level, connection is lost ... ), and relation phrase (e.g. card with code, communication between central controller and entrance). Markup each kind of concept (e.g. "card") the first time it occurs with hyperlinks (an anchor) <a href= "data_dictionary.html#card"> </a> around the concept or phrase. In the next exercise you will create the file "data_dictionary.html" and place a named anchor <a name="card"></a> in it, after which you will define the concept "card".
   
   
4. Effectively you are marking up all relevant concepts in the informal user requirements document, and linking them to a data dictionary. Notice that it is usually not necessary to create a dictionary link more than once (this is distracting for the reader). For example, the word card might occur 20 times, but you should only create a hyperlink out of the first occurence. However, you might find that the same word has different meanings in different contexts. Thus the same word may have different dictionary references in different places of the text. So the occurence of two hyperlinks would make this immediately clear to the designers.
   
   
5. When you have isolated the important requirements concepts you should begin to think through carefully what they mean.

Here is how your document might look after marking up the requirements concepts. (Note: the text below
is not a complete markup as it stands.)

Informal User Requirements

An <a href= "data_dictionary.html#entrance">entrance</a> to an office can have have four different security levels:

1. <a href= "data_dictionary.html#door"> door </a> is always locked
2. door requires a card to unlock
3. door requires a card and also a code to unlock
4. door is always locked.

The security levels of an office entrance can be altered during the day. ....

1.5. Creating the Data Dictionary

Now it is time to create a data dictionary. This is a text document that serves as a reference document for all technical requirements concepts. It provides a common and agreed vocabulary between the end users and the requirements analysists. Data dictionaries often contain a lot of domain specific terminology and notation, e.g. specific to the: banking sector, the aerospace sector, the insurance sector, etc. It is important that non-expert programmers understand the necessary domain knowledge sufficiently well on a project.

It is important to:

• provide each item included in the dictionary with a name and a brief explanation,
• categorise the concepts into nouns, verb phrases and relation phrases,
• sort the concepts alphabetically,
• have a section in the data dictionary for each activity. This is a good idea because a certain concept sometimes has different meanings in different activities, e.g. "save".

All the important nouns, relations and verbs that you found in Section 1.4 should be included in the data dictionary.

1. Create a new file called something like "data_dictionary.html".
   
   
2. Link the file "data_dictionary.html" to the hyperlink "Exercise 2: Data Dictionary" on the homepage of your project. It is now accessable from the table of contents for your project.
   
   
3. Create named subsections of the file called: (1) Nouns/Objects, (2) Verb Phrases, (3) Relational Phrases.
   
   
4. Place each noun, verb phrase and relation phrase found in under the appropriate subsection. Add them in alphabetical order. Add a named anchor e.g. <a name="card"></a> just before the start of the dictionary entry.
   
   
5. Give a text description of the concept, with an appropriate level of detail.
   
   
6. Be prepared to repeat steps 1.4 and 1.5 again later, should you need to add missing concepts, or redefine a concept.

Here is how you entries might look: try to reproduce the entries below without simply copying them.

Data Dictionary

1. Nouns/Objects

<a name="card"></a> Card - each employee working in the office gets a card and a corresponding personal code. By means of this card and code, the employee can get access to the office.

<a name="security_control_system"></a> Security control system - a system to control the access rights to an office so that no unauthorised persons can enter without permission.

2. Verb Phrases

<a name="change_code"></a> Change code - an operation done by the system operator to change the code of a card.

3. Relational Phrases

<a name="card_with_code"></a> Card with code - each employee in the office has a card with a personal code.

1.6. Creating the Use Case Model

The aim of the use case model is to capture the requirements and present them from the users point of view, thus making it easier for the end user to validate the correctness of the requirements analysis. The validation activity has been discussed in detail in the course.

The use case model consists of:

• a list of actors,
• a list of use cases,
• a number of LSCs (live sequence charts) and/or textual use cases.

The use case model is an important source of information when developing the requirements object model.

A use case is a sequence of actions showing a possible usage of a system. Use cases developed during the requirements analysis phase mainly concern the interaction between the system and its users. No message exchange within the system should be mentioned, since we are taking a "black-box" view of the system, and developing a top-down design.

Users of a system may be people with different job descriptions or roles, or names (for one specific customer), they may also be other systems, or objects outside the scope of the design project that must interact with the system. A user is not necessarily a person.

An actor is a user taking part in a use case. An actor is not necessarily an individual user, but is more commonly a role that a user can play when interacting with the system. Notice that one and the same person may play different roles. For example, if you have a PC at home, then you are probably both the end user and the system administrator, depending on how you log in.

There are three different ways to describe a use case:

1. a text description of the use case using natural language
2. a graphical description of the use case using an LSC
3. A combination of both 1 and 2.

Describing a use case using text makes it easier to model exceptions and alternative paths of action sequences. Describing a use case using an LSC will make the use case more formal and easier for validation of the requirement and verification of the subsequent design and implementation. (If you are still unfamiliar with the words "validation" and "verification", try looking them up in a good book on software engineering, or on the web.

We will develop both text and graphical descriptions of use cases, to explore and compare the two.

1. Start by creating a new file called (something like) "use_cases.html".
   
   
2. Link the file "use_cases.html" to the hyperlink "Exercise 3: Use Cases" on the homepage of your project. It is now accessable from the table of contents for your project.
   
   
3. Create named subsections of the file called: (1) Actor List, (2) Use Case Summary, (3) Text Use Cases (4) LSC Use Cases.
   
   
4. Create the list of actors alphabetically by name, under Actor List. For each actor, describe its responsibilities. You will find actors by studying the informal requirements document of Section 1.3. Important questions to ask are:
   
   - which users will need services from the system to perform their tasks?
   
   - which users are needed by the system to perform its tasks?
   
   - are there any external systems that use, or are being used, by our system?
   
   In practise, the activity of defining actors should be performed iteratively. try to find as many actors as possible to begin with. If you are not sure you have found them all, start trying to create some LSC use cases. This often forces you into discovering missing actors. Then you can go back and complete the list of actors.
   
   
5. Create a summary of use cases alphabetically under Use Case Summary. Separate the list into two sub-headings "Normal Cases" and "Exceptional Cases". Give each use case a meaningful name, and a brief one sentence description of its functionality. (You will add much more detail shortly.) At this point you just want to distinguish cases easily.
   
   It is usually easy to identify use cases by looking at the purpose of the system. To verify that you have identified most of the important use cases, you should:
   
   - look at the list of actors, and for each actor:
   
   - identify the tasks that the actor should be able to perform and the tasks which the system needs the actor to perform. Each such task is a candidate for a new use case. It is often very useful to check the informal requirements document or the data dictionary for verb phrases. These are possible candidates for use cases.
   
   For example, start with the employee actor and try to determine which actions he/she needs to perform. There are different ways to enter an office, either using a card, or using a card and a code. Both ways are candidates for the use case list. Also the employee must be able to exit the office, this will be another use case.
   
   You should try to make the use cases as complete as possible, i.e. make one complete use case rather than several minor ones.
   
   When you have found the "normal" use cases, refine them by examining the exceptions that are possible for each use case. Again look in the informal requirements document 1.2 to try to find any exceptions which occur. Notice that this document is not necessarily a complete description. (This is one of the commonest and most difficult problems of requirements analysis. In practise it must be solved iteratively by many discussions with the end user.) Therefore you may have to use your common sense, to "fill in any missing information", if you believe it is missing.
   
   For example, in the case where an employee enters the office, the first thing which can go wrong (i.e. an exception case) is that there is a communications failure between the entrance and the central controller. Other possible things which can fail are that a card is invalid, or that a code is wrong, or that the time between typing keystrokes is too long, and finally, that the door is never opened even though it was unlocked.
   
   
6. Create a list of text use case descriptions ordered alphabetically by use case name (see 5) under Text Use Cases. Each such use case description will give a detailed description of a scenario. A text use case consists of natural language text structured into text fields. These are:
   
   - Name: the name of the use case according to the Use Case Summary
   
   - Actors: a complete list of all actors involved in the use case
   
   - Preconditions: a list of properties or conditions that must be true for this use case to take place
   
   - Postconditions: a list of properties or conditions that must be true when the use case is finished
   
   - Description: a text description of the normal sequence of events that describes the interaction between the actors of the system
   
   - Exceptions: a list of exceptional interactions that complement the normal flow of events described in the Description field. If an exception leads to a different postcondition than the normal sequence of events, then this should be noted.
   
   The description field should describe what happens when everything takes place as expected (also known as the "sunny day scenario"). The exception field should describe what happens when various things go wrong (also known as the "rainy day scenario"). Thus there should be no overlap between the Description and Exceptions fields. Furthermore, (ideally) they should together cover all possibilities.
   
   
7. Create a list of LSC use case descriptions ordered alphabetically by use case name (see 5) under LSC Use Cases. Each such use case description will give a translation of the informal text use case into the more formal LSC language. An LSC use case makes use of the LSC language notations which you have learned in class.
   
   You will have to convert each LSC use case drawn using the Play-Engine into .gif or .jpeg format in order to include it into your web pages. One way to achieve this is to use a tool such as Paintshop Pro to take screen shots, and save these in either format, in order to include it them your html files through anchors.
   
   To draw an LSC for a given text use case, remember that:
   
   - each actor should be represented by a separate object instance, (timeline).
   
   - actions, displayed messages, input, outputs, etc should be drawn as LSC messages between the instances.
   
   - if a use case becomes too long for the page, break it into two or more LSCs and connect these by using LSC subcharts. You could also add some text which clarifies the relationship between the LSCs.
   The collection of LSCs obtained this way should be pasted close together in your final document for easy reading.
   
   
8. Finally, tidy up the file "use_cases.html", by adding hyperlinks and named anchors which allow you to jump between: (1) every entry in the Use Case Summary, (2) its corresponding entry in the Text Use Cases, (3) its corresponding set of LSC diagrams in the LSC Use Cases, and finally from (3) back to (1) in a cycle. This will dramatically improve the traceability of your document. (Requirements traceability is a major issue in requirements analysis.)

Here is a part of how your document should look when finished:

Use Case Document

1. Actor List.

Employee: someone who needs to enter and exit the office. To enter the office, an employee must have a registered card, and (depending on the current security level) a corresponding personal code. To exit, the employee must press an exit button to unlock the door.

Central Controller: the central controller starts and maintains the security control system. All changes to the database are handled by the central controller. The central controller is operated by a system operator.

2. Use Case Summary.

Normal Cases:

Level2 Entry Describes the interaction between an employee and the security control system when an employee wants to enter the office through a door with security level two.

Level3 Entry Describes the interaction between an employee and the security control system when an employee wants to enter the office through a door with security level three.

Exceptional Cases:

Invalid Card or Code: ...

3. Text Use Cases.

Name: Level 3 Entry

Actors: Employee, Central Controller, Door, Card Reader, Display, Keypad

Precondition The security level of the door is three. The door is closed and locked. The door display displays the message "Enter Card".

Postcondition The security level of the door is three. The door is closed and locked. The door display displays the message "Verifying Code". The central controller is verifying the code.

Description The employee swipes a card into the card reader which reads its number. The display displays the message "Enter Code". The employee enters a code consisting of four digits using the keypad. Each digit is entered within 3 seconds. The card number and the four digits are sent to the central controller for validation.

Exceptions

4. LSC Use Cases.

4. Automatically Generated Natural Language Translation.
Whenever: If Display.State=Enter Card and Door.Locked=True and Door.Open=False and Door.SecVal=3 then continue, otherwise ignore this scenario. the Employee sends Swipe(Number) to the CardReader Then: the Display its State to Enter Code, T is assigned the current time, the Employee sends Enter(D1) to the Keypad. If current time<=T + 3 then continue, otherwise exit the scenario. T is assigned the current time, the Employee sends Enter(D2) to the Keypad. If current time<=T + 3 then continue, otherwise exit the scenario. T is assigned the current time, the Employee sends Enter(D3) to the Keypad. If current time<=T + 3 then continue, otherwise exit the scenario. T is assigned the current time, the Employee sends Enter(D4) to the Keypad. If current time<=T + 3 then continue, otherwise exit the scenario. the Keypad sends ValidateCNC(Number,D1,D2,D3,D4) to the CentralController, the Display its State to Verifying Code.

1.7. Creating the Requirements Object Model

The requirements object model is meant to capture:

• the objects,
• the relations between objects,
• other design concepts

which are important for the application that is being built. Relations between objects will

be expressed through associations, aggregations and inheritance. In this final part of the exercise you need simply

display the internal object model for the security control system which the Play-Engine automatically creates.

1. Start by creating a new file called (something like) "req_object_model.html".
   
   
2. Link the file "req_object_model.html" to the hyperlink "Exercise 4: Requirements Object Model" on the homepage of your project. It is now accessable from the table of contents for your project.
   
   
3. Produce a .jpg of .gif image of the internal object map produced by the Play-Engine, and embed this image in the page "req_object_model.html".
4. With reference to the relational phrases defined in your data dictionary. Consider how these could be added as instances of associations within the object diagram. You may use the UML formalism to draw sketch such associations, by hand on a hard copy of the diagram. You can discuss your solutions with the examiner, but you do not need to submit these to complete the exercise.
5. Congratulations! You have just completed the first lab exercise and your first LSC based requirements analysis! Go and have a coffee or find some other way to unwind!