When the Bough Breaks – Alternate Scenarios

Alex returns with his blog post series on understanding use cases... 

Wow, it’s been four months since I wrote my piece on primary scenarios so this is severely overdue. I choose to blame this on the fact that one of our account managers, Ajay, appears to be offended by the idea that my calendar can have days in it that have no entries at all and does everything in his power, successfully I might add, to account for every minute of every day of my life. This has actually become something of a joke with many of our customers who, when asking me if I’m available to do something, “understand” that I must first get permission for Ajay before replying. Enough about my scheduling situation, were here to talk use cases. 

 Our previously defined primary scenario details the required behaviour of the system under “ideal” conditions and is useful in the understanding of customer requirements. The thing about customer requirements is that, even the most thoroughly defined, requirements are likely to only specify the nominal behavioural flow. Most of the customer requirements that I have read are significantly lacking in detail when things don’t go according to plan.

The use case primary scenario provides us with a clearer understanding of what it is that our customer requires but what about the things that they didn’t take into account? It is here that the alternate scenario provides answers or, in the case of most requirements, questions that need answering.

The identification of alternate scenarios is a three step process:

• Run through each step in the primary scenario and ask yourself; “what could happen differently?” to produce a list of potential alternate conditions
• Rationalise the list by removing those that the system cannot or does not need to handle and merging the ones that will be handled in the same way
• Write the scenario for each condition in the rationalised list.

During the identification of alternate conditions you should be looking for things such as:

• Incorrect behaviour on the part of either the primary or supporting actors
• Timeouts; one of the actors failing to provide a required interaction

When writing an alternate scenario the alternate condition becomes the trigger and then all we have to do is write what happens next until one of two things happen; either the primary scenario is re-joined or the use case ends because the goal cannot be achieved.

Typically the documenting of alternate scenarios is where use cases provide the most benefit in highlighting the inconsistency and incompleteness of the customer requirement.

Finally one should repeat the process on each of the alternate scenarios to identify possible alternates upon the alternates. Obviously this could be applied recursively through many levels however I tend to find that if you need more than two layers of alternates you should reconsider the scope of the use case as it is highly likely that you have attempted to include multiple capabilities that should each have their own use case.

Even with only two layers of alternates it is possible to develop far more scenarios than are actually needed, so, be sure to always question if what you are writing is adding to the required understanding of the system under development.

Next time I’ll look at how we model common and specialised behaviour in our use cases.

Use Case Based Project Estimation

We have looked at how to capture requirements with Use Cases, but once this is done, how do you progress with the project? Derek tells us in this post about the Karner's Use Case Points Method... 

How long would this UML project take to develop?

As we have seen from our series of posts on use cases, they are an excellent way of capturing our user requirements.  Before commencing development, it makes sense to estimate how long the development should take.  It also makes sense to base that estimation on those use cases, given they are the requirements we are going to implement.  There are several techniques we could use, but I would like to introduce you to the Karner method which was developed on 1993 by Gustav Karner.  This method involves the studying of the system actors and use cases, weighting them according to complexity and then applying technical and environment factors.  This process follows a number of steps:

 
1.       Weight the actors
2.       Weight the use cases
3.       Calculate the unadjusted use case points (UUCP)
4.       Determine the technical complexity factors
5.       Determine the environmental factors
6.       Calculate the Use Case Points (UCP)

1. Weight the Actors

The first step of the process is to analyse the complexity of your actors. The level of complexity is divided into 3 Actor Types:

Assign an actor type to each of your actors and then use the formula to calculate the total weighting

Σ(Number of each Actor type *  Appropriate Factor) 

Simple actor represents a separate entity which can be communicated with via an API. This means that interactions with the actor should be simple top implement. The multiplication factor for a simple actor is 1.

Average actors represent an entity which communicates by a defined protocol such as TCP/IP or RS232. This represents a more complicated interaction and thus the multiplication factor is 2.

Complex actors represent a person interacting with the system through a user interface. Obviously this interaction process is very complicated and therefore warrants the highest multiplication factor of 3. 

Once you have weighted your actors you need to add up the total number of each actor type and then multiply the 3 totals by the appropriate multiplication factor. These values then need to be added together. 

2. Weight the Use Cases

The next step is to analyse the complexity of your actors. The level of complexity is divided into 3 use case types:

Once you have weighted the actors we need to weight the use cases themselves.  For each scenario in our use case we need to calculate the number of transactions. A transaction is described as the completion of a request from a primary actor by information being dispatched to all relevant supporting actors 

Σ(Number of each use case type *  Appropriate Factor) 

3. Calculate the Unadjusted Use Case Points (UUCP)

Once the number of transactions for each use case has been determined, you should weight them as described in the above table. We then follow the same equation which was presented for the actor weighting.

Once we have this total we can calculate the unadjusted use case points (UUCP) by adding the two weighting totals together.

Unadjusted Use Case Points = Actor weighting + Use Case Weighting

4. Determine the Technical Complexity Factor

Now we need to determine the technical complexity of the project, this process involves us analysing each entry in the table and assigning a rating between (0-5) for each row.

Tfactor = Σ(Rating * Factor)

Now calculate the Technical Complexity Factor using the following formula:

TCF = 0.6 + (0.01 * TFactor)

5. Determine the Environmental Factor

We now need to consider the people working within our team. They will have different strengths and experiences. This factor is called the Environmental Factor (EF).  To calculate the EF we follow a similar procedure to that discussed for the TCF.  As before we have to analyse each entry in the table and assign a rating  between (0-5) for each row.

A rating of 0 indicates that we have no experience in the field. A value of 5 means that we are experts in this area.  Again, once you have justified your decisions you can multiply each element by its weighting factor.  The summation of these values gives you the EFactor for your project:

Efactor = Σ(Rating *  Appropriate Factor)

Now calculate the Environmental Factor using the following formula:

EF = 1.4 + (-0.03 * EFactor)

6. Calculate the Use Case Points (UCP)

Once you have calculated the 3 factor readings (UUCP, TCF and EF) we can multiply them together to give us the use case points (UCP) for our project.

UCP = UUCP * TCF * EF

We can use this value to estimate how long the project should take to develop. The Karner process suggests a value of 20 man hours per UCP for this estimation, so to estimate project duration use this formula:

Project man-hours = 20 * UCP

With experience, this figure can be refined, personally  I believe people this figure should be increased when dealing with large teams as team cohesion becomes a bigger issue.

For a more accurate estimate you can add the number of environmental factors 1 to 6 that are above 3 to the number of factors in 7 and 8 that are below 3. If the total is 2 or less the figure of 20 hours is used. If the value is 3 or 4 a value of 28 should be used to calculate the project man hours.

Based on the above, I would be interested to hear what people think could be done to improve reduce a projects estimated cost?

We have developed a Use Case Estimation Tool to assist you in successfuly managing your projects. 

Go to our website to find out how this could support you and your project...

Adding Flesh to the Bones – Primary Scenarios

Alex, one of our Systems Engineering trainers, continues to share his wisdom in another post in his series on Use Cases. 

Having defined the structure of the use case it is now time to describe the behaviours and interactions that occur during the execution of the use case; the flow of events if you like.

For this we will write use case scenarios to document the dialogue between the system and actors as the use case achieves its goal.

A scenario is an instance of a use case, i.e. it is one flow through the use case.  Each use case will have many possible paths through.  We first write an easy to understand description of a typical scenario in which the use case delivers the primary actors goal, i.e. the actor gets what he/she wants.  This main scenario is frequently known as the primary scenario.  All other paths through success and failure are described as extensions to the primary scenario, sometimes called alternate scenarios.

Let's bring in the ATM example.

Use case scenarios are normally captured using simple text.  Each scenario captures a specific path through the use case in a single flow of events that contains no branching. There is one primary scenario and several alternate scenarios documenting all of the relevant success and failure cases.

 It can be difficult to describe iterations, branching and/or concurrency using text, and therefore scenarios can be also described using sequence, state machine or activity diagrams. For now let us concentrate of the text. 

Textual scenarios are written as a sequence of goal-achieving actions by the various actors. Each action step will describe one of the following:

• An actor interaction         -              “Customer enters PIN” 
• A validation step              -              “System validate PIN code”
• An internal change           -              “System deducts amount from balance”

There are a number of useful guidelines for use case scenario action steps:

• Use simple grammar and vocabulary
• Write everything in the same tense
• Show clearly who is involved in each step
• Write from a consistent perspective
• Show the process moving forward
• Show the actor’s intent not how he does it
• Limit each scenario to between 3 and 11 action steps
• Number each action step

As with all modelling your first draft is unlikely to represent the final incarnation of the primary scenario and may need to be modified once the alternate scenarios have been written. That, however, is a discussion for another day.

Not All Stories Are Told at Bedtime – Documenting Use Cases

Systems Engineer, Alex shares more insights into documenting use cases in his latest post... 

Having reached the point where we have identified our use cases and represented them on one or more diagram; the time has come for the real work to begin.

The use case name, use case diagrams and use case briefs / descriptions provide a high-level abstract view of what the system must  (or will) do.  Behind each use case is a structure that describes the use case in more detail.  This structure identifies the specific behaviours and interactions that occur between the actor and the system with the use case’s flow of events.

The structure contains the following fields:

·         Description - Describing the role and purpose of the use case

·         Trigger  -   What starts the use case executing

·         Pre-conditions  -  What must be true before the use case executes

·         Post conditions  -  What is true after the use case executes

·         Primary scenario  -  The activities the system performs

·         Alternate scenarios   -  Alternative flow of events, variations in behaviour

The purpose of this structure is to capture what has to be done by each use case to accomplish the functionality.  We must consider the basic functionality, any alternatives, error conditions, anything that must be true before the use case executes and anything that is true on exiting the use case. Let’s examine these further.

A trigger specifies the event that starts the use case executing, for example, a cash machine wakes up when the customer inserts his/her card.  Often the trigger is the first step in the flow of events / scenario(s).

Pre-conditions describe the state of the system before the use case runs.  What must be true in order for the use case to execute. Pre-conditions apply to the state of the system, not the outside environment.  A common mistake is to write pre-conditions that that are often or sometimes true, but not always. Examples of pre-conditions are: “The user is logged on”, “The target has been selected” etc.

Post conditions describe the state of the system as result of the use case executing.  A use case can either fail or succeed and therefore it is difficult to write post conditions that hold true in both situations.  

Pre and post conditions can help identify dependencies between use cases.  Remember, they are states the system is in either before or after a use case executes. While pre-conditions can be identified early on, the post conditions will only become apparent after the scenarios have been written which I will discuss in my next post.

A Picture Isn’t Always Worth 1000 Words – Use Case Diagrams

In his next post in the series, Alex looks at the next step in creating a useful use case... 

 At this point in our development of a use case model we have:

•  Identified the actors
• Categorised the actors into primary and supporting
• Identified goals for the primary actors

The next stage is to represent the actor goals as use cases on a diagram. Although the actor goals may not map directly to individual use cases it is often a good place to start.

While the use case model contains all the actors, use cases and their relationships; use case diagrams are views into the model and graphically represents actors use cases and the connections between them.  For large systems, many use case diagrams will be needed to communicate the use case model.

In UML and SysML a use case is drawn as an ellipse and contains a name which represents the system functionality described by the use case.  Use cases are then placed on use case diagrams with the actors and the relationships between them added (usually represented as an association in most UML/SysML modelling tools).  In some cases you might wish to add a system boundary box around the use cases with the actors outside the box.

When identifying our primary and supporting actors in the model it was not possible to categorise them as either as there are many instances where an actor might be primary for one use case but supporting for another. As a convention most developers place primary actors on the left of the diagram and supporting actors on the right.

The simple nature of use case diagrams often leads people to believe that use case modelling is easy while nothing could be further from the truth.  A small system can be expressed with a small number of use cases involving two or three actors.  As you tackle larger systems, it will become obvious that this is not a menial or insignificant task.    

In essence use case diagrams can be used to represent or validate the system context but the true power of a use case lies in what sits behind the diagrams.

Do not be fooled into believing that you can just focus on bubbles and stick men while ignoring the detail that sits behind them. Use cases a means on analysing and communicating the detail in the textual requirements and cannot be used to replace them.

He Shoots! He Scores! – Finding Actor Goals

Alex, our expert Systems Engineer, continues to help us fully understand use cases and their purpose with his latest blog post...

Identifying the primary actors has allowed us to validate the context of the system however it is the goals of the primary actors that we are really looking for as they will help us discover our use cases.

An actor goal represents a service that the primary actor requires from the system.

A use case is always started by an actor and so focussing on the actors yields good results.

In addition, there may be external events that we must react to such as start-up, shut-down and time related events that we might not have considered given our set of actors. When identifying actor goals we should consider:

• What are the tasks of an actor?
• Does the actor need to be informed about certain occurrences in the system?
• Are there any external events that affect the system? What actor informs the system about those events?
•  How the system starts-up and shuts down
• How the system is maintained?
• How will we handle training users of the system?
•   Does the system store information? What actors will create, read, update or destroy that information?

A table is often created during this phase and is frequently referred to as an actor goal list.  If a large number of primary actors have been created then this table is likely to be quite extensive. This is not overly significant as the worst that is likely happen is that we will generate the same goal more than once.  Once the actor goal list has been generated, the list must be reviewed and rationalised.

The rationalised actor goal list provides an initial list of use cases that must now be documented.

It is likely that you will not find all the goals during this stage, no matter how careful or diligent you are.  New ones will appear when documenting the use cases.

…and the Oscar Goes To – Primary and Supporting Actors

Alex continues with his series of posts on use cases and looks at the Colin Firth's and the Geoffrey Rush's of the use case world...

Previously we discussed the identification of actors that will interact with the system under development. The next activity to be performed in the development of a use case model is to categorise those actors. Actors are usually divided into what we refer to as primary and supporting actors.

A primary actor is a user who will use the system to achieve a goal.  The needs of the primary actors drive the behaviour or functionality represented in the use case.  If the primary actor roles or needs change, then it is likely that significant modification to the system will be required.

The primary actor is often, but not always, the actor who triggers the use case.  Usually, the use case starts because the primary actor sends a message to the system, pushes a button or in some way triggers the story.  There are two common situations in which the initiator is not the primary actor:

• The initiator starts the use case on behalf of another actor
• The use case is triggered by time

 For an individual use case, any actor that is not primary will become what is known as a supporting actor.

Supporting actors provide a service in the use case and would not exist if there were no primary actors.  Supporting actors typically participate in the use case to support creating value and achieving a goal for the benefit of the primary actors.

Supporting actors are used to identify external interfaces the system will use and the protocols that cross the interfaces.  This feeds the other requirements, such as data formats and external interface descriptions.

Remember that an actor may be primary in one use case but supporting for another so it is not possible to universally classify the actor as its role may differ between use cases.

The identification of primary and supporting actors is a key step to discovering what our use cases will be as the use cases represent goals that the primary actors wish to use the system to achieve.

Not All Actors Live in Hollywood – Refining the System Boundary

It's the awards season and we're looking forward to seeing what happens at the BAFTAs on Sunday. But in this post we're not talking about Mr. Firth or Miss. Portman, we're talking about use case actors as Alex continues with his interesting series on use cases...

Before building a new system it is essential to clearly define its boundary.  This means understanding what sits within the systems, that we must develop, and what sits outside, that we must interface with.

Given any requirement specification, it is usually easier to identify what sits outside the system boundary and use that to determine how the system responds when it is stimulated from its environment, or how the system is going to be used.

When an event occurs, that causes an interaction between the system and its environment; entities within that environment are involved.  Some of the entities initiate the event; others interact with the system as a result of the event.  In use case modelling, these entities are known as actors.

An actor is an entity that interacts with the system for the purpose of achieving a goal or completing an event.  Actors are not necessarily human users of the system; they can be other systems or even external forces that act upon the system (although the latter is unlikely to be a consideration when modelling software).

When looking for actors, review the following sources of information for potential actors of the system:

•       Existing context diagrams and other models that describe the boundary of the system with its environment.  Look for external entities that have interaction with the system

•       Written specifications and other project documentation, such as records about meetings with users, these help identify users who may be potential actors

•       Training guides and user manuals.  These manuals are normally directed at roles representing users and therefore potential actors.

Each actor needs a descriptive name that indicates the role it plays and a brief description that is one or two sentences long.

The description should include:

•       What the actor represents

•       Information about the actor’s capability, functionality or skills

•       Why the actor is needed

•       What interest the actor has in the system

Many use case modellers forgo the description of actors and merely give them names which, in the case of systems, is often just the name of the system itself. Remember, when you document your use cases you will detail specific interactions with the actors and have little chance of getting it right if you don’t fully understand the actor to begin with.

Actors are a means of identifying and documenting the users of the system so that the users’ needs can be modelled, validated and implemented.  The goal is to ensure that the system ultimately meet their needs.

Alex

Round Pegs into Round Holes – Where Use Cases Add Value

 Alex looks at another issue with Use Cases and how they only add value when used in the right circumstances. This post was inspired by a discussion on the Model Driven Software Network.

One of the criticisms levelled at use case modelling as a technique is that it duplicates information that already exists in the textual specification. This can be true if you create use cases for their own sake.When performing any kind of systems or software modelling it is important to understand that the model should add value.

Use cases serve as a means to communicate from one person to another without any special training. Their purpose is to allow clarification and understanding of stakeholder needs by capturing the primary capabilities of a system.

In an age where customers are becoming more driven by filling capability gaps and less likely to provide detailed requirements, use cases are an extremely effective means of developing a requirement set where none exists.

Even where there is some form of contractual requirements document use cases can still be employed to validate those requirements. Never in the field of system development has there ever been a set of consistent, unambiguous and complete requirements delivered at the beginning of the project. 

Use cases add value when:

• They allow developers to see what the system needs to do.
• They help to elicit system requirements.
• They help to validate the system context.
• They help to identify conflicting stakeholder needs.

Even though it might sometimes seem that developing use cases is a duplication of effort, experience shows that validating the requirements saves considerable time, effort, money and frustration later in the development lifecycle.

If we don’t get the requirements right we may still build the system right but we have little chance of building the right system.

 

Alex

If there is a topic you would like to see discussed on our blog please let us know by commenting on the blog or messaging Cat on LinkedIn.

Stakeholders Don’t Just Kill Vampires – Sometimes They Talk

Alex continues to blog valuable insights into the art of capturing requirements...

Typically requirements analysis begins with some sort of user requirement document (URD) and often engineers consider this to be the only source of input. In modern development, however, customers are producing fewer requirements but, instead, becoming more capability driven. What this means is that, rather than identify a long list of “The system shall…” statements, customers are identifying gaps within their capabilities and asking industry to propose an appropriate solution. In order to effectively handle this absence of a URD it is vital that engineers take the time to identify and investigate the needs of the system stakeholders.

 So what is a stakeholder? As my title suggests, in this context, it is not Buffy the Vampire Slayer; nor is it the waiter at your favourite restaurant. A stakeholder represents anyone who has an interest in the system for some part of its development or operation. The obvious stakeholders are those who are paying for its development and those who need to use the system but is that where it ends? What about internal stakeholders? I know that whenever I develop anything that Derek looms over my shoulder wanting to know if the deadline will be met and whether I’ve blown the budget or not (naturally I never do). As a requirements engineer I have to take into account, not only those whom the final product will be delivered to but also those who will take my work and further the development; designers, implementers, testers – they are also my customers.

Successful development is based on good communication. Regardless of how your system functions, the project has failed if it doesn’t meet the needs of your stakeholders and the only way to guarantee that it will is to involve them in the development process all the way through. Learning how to ask the right questions is as important a development skill as understanding the technology on which the system is going to be based.

Alex

Putting the System in its Place – Context Diagrams

Alex continues discussing capturing requirements, this week looking at Context Diagrams and how they can help us understand the environment in which the system under development can operate... 

Although not strictly related to use cases, which I have previously stated as the theme of my series and upcoming posts, the development of a context diagram is an excellent first step in understanding the environment in which the system under development (SUD) will operate.

While some might consider this an unnecessary step in development I find that the development of a separate context diagram has two major benefits. Firstly it allows you to model elements which do not directly interact with you system but indirectly affect it and secondly it allows you to consider different system usages.

With regard to the former you might ask “why would I want to model things that don’t directly affect my system?” Take, as an example, the command and control (C²) for a complex weapon system (credit must be given here to my colleagues who worked with me to develop the example I am using – I’d tell you who they were but then I’d have to kill you). On a use case diagram you would represent things that directly interact with you system but at no point does your C² directly engage the target, it is the weapon itself that does that and it would be illegal UML or SysML if you modelled the interactions between the weapon and the target as it is out of scope. Not modelling this, however, does not accurately represent the system purpose as you end up with a model that explains what your system does but not why. A context diagram showing the larger scope of system usage is the perfect place to communicate this.

In my title I refer to context diagrams (plural) and have done so deliberately. A good system (or software) model considers more that the, obvious, operational context. There are many other points of view to be considered; as an example I cite the defence lines of development (for the purposes of not defence developers I have attempted to demilitarise them – the MoD definitions can be found at http://www.aof.mod.uk/aofcontent/strategic/guide/sg_dlod.htm):

•  Training - the provision of the means to practise, develop and validate, within constraints, the practical application of a capability.
• Equipment - the provision of platforms and systems needed to outfit an individual, group or organisation.
•  Personnel - the timely provision of sufficient, capable and motivated personnel to deliver outputs.
• Information - the provision of a coherent development of data, information and knowledge requirements for capabilities and all processes designed to gather and handle them.
• Concepts and Doctrine - a concept is an expression of the capabilities that are likely to be used to accomplish an activity in the future. Doctrine is an expression of the principles which guide actions and is a codification of how activity is conducted today.
• Organisation - the organisational relationships of people.
• Infrastructure - the acquisition, development, management and disposal of all fixed, permanent structures in support of the required capabilities.
• Logistics - the science of planning and carrying out the operational movement and maintenance.

Remember that your first attempt at context modelling is likely to be based on a limited understanding of the system and is therefore merely a starting point. Further analysis of the requirements will result in a refining of the system boundary and is likely to cause the context to change. As with all good development, producing a system context is an iterative activity.

Alex