In this lab we will extend our initial user stories into fuller use cases, trying to capture the detail of the work we require to complete the new HR System. We will also look at Use Case Diagrams to visually define our use cases and their relationship.
- Define use cases using Cockburn's Use Case Template.
- Define use case diagrams using PlantUML.
In Lab 03 we defined our eight user stories from our vision statement:
- As an HR advisor I want to produce a report on the salary of all employees so that I can support financial reporting of the organisation.
- As an HR advisor I want to produce a report on the salary of employees in a department so that I can support financial reporting of the organisation.
- As an department manager I want to produce a report on the salary of employees in my department so that I can support financial reporting for my department.
- As an HR advisor I want to produce a report on the salary of employees of a given role so that I can support financial reporting of the organisation.
- As an HR advisor I want to add a new employee's details so that I can ensure the new employee is paid.
- As an HR advisor I want to view and employee's details so that the employee's promotion request can be supported.
- As an HR advisor I want to update an employee's details so that employee's details are kept up-to-date.
- As an HR advisor I want to delete an employee's details so that the company is compliant with data retention legislation.
So far, we have implemented user story 1 and 6. As an exercise, you are expected to complete all the use cases defined above. This lab will only provide one example: user story 4. However, you should be able to complete the use case for 1 and 6 from our previous work, and we will be reviewing the other use cases through the rest of the lab series.
From Wikipedia:
In software and systems engineering, a use case is a list of actions or event steps typically defining the interactions between a role (known in the Unified Modeling Language (UML) as an actor) and a system to achieve a goal.
To simplify, a use case is:
- a list of actions/events;
- by an actor;
- interacting with a system;
- to achieve a goal.
Our user stories are a form of use case, sometimes referred to as a casual use case. The user stories we have defined two elements directly and one indirectly of a use case. For example, let us consider use case 4:
- no list of actions defined.
- HR advisor (actor).
- interacts with HR system.
- to produce a report on the salary of employees of a given role (goal).
Our user stories are lacking in the following two areas:
- there is no list of actions.
- the system interaction is opaque.
A fuller use case will allow us to address these two issues. The list of actions we are normally defining as we build a feature. Let us put some thought into the actions beforehand, but remember that details can change! We are planning but not putting our plan in stone until we have finished a feature.
Lecture 10 goes into more detail about use cases. Here, we are going to cover the application of these ideas. We are going to use a version of Cockburn's Use Case Template. You can see a sample of Use Case 4 using this template style.
Cockburn's template contains the following sections of note:
- Goal in Context - we will use our user story.
- Scope - is discussed more in the lecture. Scoping is an important consideration in any work you do.
- Level - what level is the use case targeted at. This is discussed further in the lecture.
- Preconditions - what do we expect is true before the use case is executed.
- Success Condition - what will happen on completion of the goal.
- Failed Condition - what will happen on failure of the goal.
- Primary Actor - the main actor of the use case.
- Trigger - how is the use case started.
- Main Success Scenario - what are the steps leading to success.
- Extensions - what might happen at a given step to stop the use case.
- Sub-variations - any other branches that a step can take?
- Schedule - when does the use case need to be delivered.
First, create a new folder in your project called use-cases. Copy the use-case-4.md file provided into this folder.
Your exercise is to complete the other seven use cases for the HR system. Write these in Markdown (.md files). IntelliJ comes with a default plugin to support Markdown. If you are unfamiliar with Markdown, then there are several tutorials available. This is a good opportunity to work with your team.
Use cases can also be visually represented using a Use Case Diagram. Typically seen as part of the Unified Modelling Language (UML) (see Lab 6 and Lecture 11), use case diagrams allow us to see how use cases interact simply. However, they do lack the detail required to fully implement and understand features, and therefore should be seen as a support tool for software development. In particular, they can communicate with stakeholders quickly about how the engineers see the system working.
Use case diagrams are quite simple, requiring only stick men, arrows, and ellipsoids at the most basic level. We will cover the common use case symbols from UML below.
To illustrate a use case we use an ellipsoid with text as below:
Actors are represented by stick figures:
Use cases can also relate to each other, typically in include and extend cases. Below is the diagram:
An include relationship is one where a use case includes (i.e. uses) another use case to perform its functionality. An extend relationship is one where a use case extends (e.g. supports an edge-case) from another use case. It provides a special version. These should have been identified in the Extensions section of the use case.
A use case typically exists within a system, or communicates with another system. For example, see below:
Use Case 1 and Use Case 2 both exist within the System. Use Case 2 also communicates with an external system - Database.
There are quite a few UML diagramming tools out there. However, we want to store our diagrams in our GitHub repository. As Git repositories don't like binary files, we will use a textual representation via PlantUML. This is a common textual standard to describe UML diagrams and can be used to generate images. We will do this via an IntelliJ plugin.
To use the PlantUML plugin in IntelliJ you will first need to install GraphViz on your machine. GraphViz is a graph drawing tool that several tools use to layout diagrams. Download instructions for GraphViz are available from here. For Windows users, install the stable release.
Next we need to install the PlantUML plugin for IntelliJ. Go to File, Settings then Plugins to open the Plugins Window. Search for PlantUML. The plugin you want is PlantUML integration as shown below:
Click Install, then Accept and finally Restart IDE. Once IntelliJ has restarted, PlantUML should be available.
To see the PlantUML is set up correctly we need to create a diagram. Right click on the use-cases folder, select New, and the UML Use Case. Give it the name HR System and click OK. This should provide you with the following window:
If you don't see screen as above a couple of things to check:
- did you install GraphViz?
- if so, open the settings for PlantUML (click the small spanner above where the diagram should be), and browse for the dot executable which will be where you installed GraphViz.
A more comprehensive guide is available here. We will examine the basics.
A PlantUML file starts and ends with the following:
@startuml
@enduml
We define a use case as follows:
usecase "Use Case"
We can also provide a name for the use case. This makes it easier to connect them later:
usecase UC1 as "Use Case 1"
usecase UC2 as "Use Case 2"
Actors are defined as follows:
actor "Actor"
And they can likewise be named:
actor A1 as "Actor 1"
actor A2 as "Actor 2"
There are numerous methods to lay out arrows - see the tutorial. For example:
actor A1 as "Actor 1"
usecase UC1 as "Use Case 1"
A1 --> UC1
Systems can be defined using rectangles:
rectangle Database
rectangle System {
usecase UC1 as "Use Case 1"
UC1 --> Database
}
Anything defined within the rectangle curly braces are part of the System.
Let us look at an example from our system. Below is use case 4:
@startuml
actor HR as "HR Advisor"
rectangle Database
rectangle "HR System" {
usecase UC4 as "Get salaries
by role"
usecase UCa as "Print salaries"
HR - UC4
UC4 ..> UCa : include
UC4 - Database
}
@enduml
This will produce the following diagram:
Your task now is to complete the use case diagram for the entire set of use cases defined. You only need one diagram for all the cases. Again, work with your team, and seek feedback. We will revisit various parts of the diagram throughout the module so you can adjust as you are going along.
Now it is time to work on our next feature - user story 4: As an HR advisor I want to produce a report on the salary of employees of a given role so that I can support financial reporting of the organisation.
Remember the steps you took last week for executing a Sprint:
- Decide which user story/stories to work on for the next Sprint.
- Create a new Sprint on Zube.
- Add the user story card(s) to the Ready column in Zube.
- Add any additional task cards to Zube and put in priority order.
- Pull the latest
developbranch. - Start a new feature branch for the task(s) or user story.
- Select task to work on in Zube.
- Work on task.
We only have one task to do this week: get the salaries by department. This is very similar to the last feature - get all salaries - but with an additional restriction. Therefore it is your task to implement this feature on your own.
The SQL required for this query is below:
SELECT employees.emp_no, employees.first_name, employees.last_name, salaries.salary
FROM employees, salaries, titles
WHERE employees.emp_no = salaries.emp_no
AND employees.emp_no = titles.emp_no
AND salaries.to_date = '9999-01-01'
AND titles.to_date = '9999-01-01'
AND titles.title = '<title>'
ORDER BY employees.emp_no ASC<title> is replaced by the name of the role (title). For example, the end of the Engineer salary information is:
...
499838 Annemarie Peroz 53972
499843 Vitaly Zucker 66847
499855 Constantine Michaels 49559
499856 Yoshinari Theuretzbacher 50966
499857 Leszek Tempesti 60478
499896 Gianluca Rando 59952
499900 Leon Baba 51414
499904 Kazuhiro Velasco 47104
499913 Masako Heiserman 73788
499918 Hilary Rodiger 55843
499927 Manohar Heemskerk 83769
499935 Ymte Perelgut 77520
499936 Chiranjit Himler 54253
499948 Cordelia Paludetto 45625
499962 Yongqiao Dalton 57667
499973 Lobel Taubman 61400
499979 Prasadram Waleschkowski 54088
499990 Khaled Kohling 45512
499993 DeForest Mullainathan 44305
499995 Dekang Lichtner 52868
499999 Sachin Tsukuda 77303 And now end your Sprint and clean up. Follow the process as defined at the end of Lab 4.