Actors and Use Cases in UML

The Unified Modelling Language provides a diagram type that can be used to model use case architecture at a high level. This use case diagram does not give any detail of the use cases themselves, and as such is not a very valuable diagram as far as a developer is concerned. However, it does give a high level view of which use cases are associated with which actors. If incorporated as part of a hyperlinked document, such as a web site, the diagram can serve as a visual contents page, each item appearing on the diagram hyperlinking to the detailed textual description of that element.

In a use case diagram, an actor is represented by a stick-person, and a use case by an ellipse. The connection between them is drawn as a line. The line indicates that the actor participates in that use case. There is no notation for indicating whether the actor is the initialtor of the use case or just a participant. To capture that detail, it would be necessary to look at the use case's detailed description.

The diagram below shows the 'thirsty person' actor participating in the 'buy canned drink' use case:

Packages and Grouping

Since most systems have a significant number of use cases by the time all the requirements are captured, it is usually beneficial to group use cases into packages. A package is a collection of use cases that share a common purpose, that service a common persistent entity in a database, or that represent the collection of goals a particular actor has. The grouping mechanism allows us to better organise and understand the areas of functionality our system is required to have. It often leads on to high level architectural decisions that partition the implementation along similar lines.

There is a UML packaging notation that is used to draw enclosed regions around groups of use cases in a use case diagram. in reality though it is of more value just to organise the use case descriptions into families and put them into a named package. The notation is incidental.

The final format for a use case

After a number of iterations round the requirements loop, use cases begin to stabilise. At this point, it may no longer be wasted effort to document these use cases according to a standard 'fully dressed' use case template. This will now constitute the use case as a single functional requirement in its final form in a requirements document.

There are many different templates representing final use cases in great detail. Here we give an explanation for the version of final template included in the Use Case Editor tool. It contains just about all of the sections you'd expect to see in other templates, and is highly suited to representing full details in an output document.

Each section of the template is listed and described below.

Use case name

This is the short name by which the use case will be known and referred to from other parts of the documentation. It is usually based on the goal that the actor is trying to reach, and is also usually in the form verb noun-phrase. The verb and noun are chosen from the point of view of the actor who is trying to reach the goal. Hence for our coke dispenser use case, a suitable title might be: "Buy drink from machine". Note that a title like "Sell drink to customer" is not suitable, as it is expressed from the point of view of the system being implemented. Stakeholders regard systems as supporting the business rather than having goals of their own, hence the name chosen from the actor's point of view.

Other use case this use case extends

Extension use cases are explained elsewhere, but basically there are some circumstances when we might wish to model a new use case that is actually a sequence of steps that can only run at a particular point inside another use case. If this is true, we identify the name of the use case being extended by this use case here.

Initiating actor

There will be a particular role or actor that causes this use case to start running. usually this is the actor who desires the goal be reached. Often, this would be the only actor involved in the use case.

Participating actors

In some cases additional actors join in with a use case after it has begun. These are not the initiating actor, but they may benefit from the original goal being reached, or possibly even subsidiary goals of benefit to them. For example, in a use case describing the sequence of steps for making a phone call through the telephone network, the caller would be the initiating actor, but the callee who picks up the phone after it rings would be just a participating actor. They are still a valid actor though, as they can hang up their phone at any time later, and thus influence the sequence of steps through the use case.

Use case preconditions

The preconditions that must be true before this use case is allowed to run would be described here. Note also that extension use cases always have a precondition that is testable within the use case being extended. This precondition represents the branch condition that takes us from the originating use case across to the extension use case, rather like an alternative path within one use case.

Primary path

The sequence of steps in the primary path are listed in this section. In the fully dressed template, this is usually structured as a numbered sequence of steps, rather than an informal single paragraph. The step numbering serves to make the primary path more readable, and also makes extension points for alternative paths easier to identify, since they are now just step numbers. An example for the coke machine might be:

1.  Thirsty customer selects drink type on front of coke machine

2.  Coke machine displays price of selected drink and prompts for cash insertion

3.  Customer inserts coins until required balance reached

4.  Coke machine drops selected drink onto collection hopper

5. Inventory and internal cash ledger adjusted appropriately

Postconditions

​The success guarantees are listed, followed by the minimal guarantees, each under their own sub-section. Note that some templates don't bother with minimal guarantees. Other templates list a set of postconditions for each alternative path that ends the use case via a different route. Which of these approaches you go for largely depends on how closely you follow the use case documentation when producing the use case acceptance tests.

Related non-functional requirements

Some templates would cross-reference the subset of non-functional requirements that have an impact on the implementation of this use case. This is useful for constructing tests for the NFRs that have an impact on this use case.

Alternative paths

Each alternative path follows on beneath the primary path description, and uses a subset of the sections listed above for the primary path. Specifically, for each alternative path we would describe:

* The extension point (as a step number after which the alternative path branches);

* The precondition that must be true at the extension point for the alternative path to be taken;

* The numbered list of steps that make up the alternative path;

* The remerge step number before which the alternative path remerges onto the primary path. Alternatively, explicitly state this is an end of the use case.