DocumentationEnterprise Architect (Sparx)Smart use casesUMLUse cases

Describing (smart) use cases using Enterprise Architect 8. Part II – Use case scenarios and structured specifications

Enterprise Architect by Sparx Systems is a commonly used modeling tool, targeted at modeling UML and BPMN diagrams. One of the most frequently used diagrams is the use case diagram. A use case diagram consists mainly of actors and use cases, either traditional or smart use cases.

Use case scenarios

There’s different ways of modeling and describing what action a use case is comprised of. In general we consider use case scenarios. Each scenario describes a way the use case can be executed. There’s three types of scenarios:

  • Happy day scenario. Executing this scenario leads to the desired result, being the goal that the actor wants to achieve, via the optimal path.
  • Fail scenario. Running this scenario results in not reaching the desired result, but to an alternate result where the actor does not achieve his goal.
  • Recovery scenario. During this scenario some anomaly is encountered that leads of the optimal path, but using some additional action, in the end the positive result is reached, and the actor’s goal is achieved.

Each scenario consists of a number of consecutive steps. As you might expect every result that can be reached is in fact a post-condition of the use case. In my opinion thus use cases can (and will most often) multiple post-conditions.

Scenarios are very useful when it comes to testing the functionality of a use case, as testers are used to describe test cases that match one of the scenarios.

Use case scenarios, basic flows and alternative flows

In Enterprise Architect and most other modeling tools scenarios are not literally described as such, but rather use a different terminology, based on flows. Here a basic flow represents the happy day scenario. Next to the basic flow modeling tools represent alternative flows. Unfortunately these do not always map to either fail or recovery scenarios.

An alternative flow is described as a replacement of one or more of the steps of another flow – either the basic flow or another alternative flow. This differs from scenarios. An alternative flow does not describe a particular scenario, but only a part of it.

Combing the basic flow with one or more alternative flows again leads to a scenario – always a fail or recovery scenario – if it ends at one of the post-conditions of the use case. To facilitate the use of basic and alternative flows, the steps they (similar to scenarios) describe are usually numbered.

Alternative flows and exception flows

Enterprise Architect distinguishes alternative flows and exception flows. Although the concept and differences are not explained, in general an exception flow is modeled when something goes wrong during the execution of a use case, for instance if some validation fails. An alternative flow is modeled when execution is correct, but takes a slightly different path than the basic flow. For instance, the user presses a button that executes some additional action.

In general when the execution of an alternative or execution flow is finished, the flow returns to the calling flow. In theory this can be any other flow. However, Enterprise Architect (using structured specifications) only allow for a single level of alternate and exception flows – which is good because it disallows complex scenario’s. After a flow is finished, the flow can return to the calling flow, but it might also end the use case, resulting in reaching one of the post-conditions.

Structured specifications

Use cases are usually specified in Word or other text editors, because there’s few tools that allow for a more structured way of defining numbered flows. Although writing plain text allows for maximum flexibility trouble arises as soon as the numbering of the steps needs to change, due to newly inserted steps or steps that are deleted. Here, references to these steps from other flows need to be updated too.

From version 8.0 Enterprise Architect offers the possibility of writing flows in a more structured approach using the structured specifications tab in the use case properties window.

SNAGHTML13ddde6_thumb[1]

Although not perfect, this structured specification offers a number of other interesting additional features:

  • Generate activity diagram. The tool can generate an activity diagram that displays all scenarios for the use case, based on the structured specifications, quite similar to how it is described in my UML book.
  • Generate test documentation. Using a document template, the tool allows for quite extensive generation of the test scenarios for the use case.

So structured specifications is an interesting alternative for writing use case scenarios. Some tips.

Tip. First write basic flow

Start with describing the steps for the basic flow. Do not add any of the alternate of exception flows yet. A basic flow contains all steps that are required to reach the goal for the use case, or the success post-condition.

A flow does not include if-then constructs (these will be alternate or exception flows). However loop constructs can appear.

Tip. Actor or System

Start each step with the actor executing the step. If there’s only one actor, I’d prefer the term Actor – to avoid issues when the name of an actor changes in the model. Steps that are executed by the system always start with the term System.

image

Note that Enterprise Architect specifies an icon in front of the steps indicating actor or system. This icon can be flipped from the context menu (although it should recognize it when you type Actor or System).

Tip. Note called use cases

When modeling smart use cases, in some steps of your flow other use cases might get called. Describe calling the other use case as a single step, executed by the system.

image 

As shown in step 6 we use the syntax System starts [Use case name], and sometimes add the parameters we pass to the called use case. In the Uses column of the structured specification, we note the name of the use case, as this column immediately shows when looking at the specification.

Note that unfortunately that if names of use cases are changed in the model, the references to use cases in the structured specifications do not change. This would however make a very interesting new feature.

Tip. Check post-conditions of called use cases

Right after a use case is called, such as Select Contact in step 6 in the example above, you should check for the post-conditions of this use case. In most cases, the positive post-condition for the called use case is the desired result. Note this post-condition in the next step.

In the example above step 7 mentions Other Contact is selected. This literally is one of the post-conditions of use case Select Contact. Although this step is not necessarily an action, such as regular steps are, it is of vital importance that post-conditions are checked. Moreover, adding the positive post-conditions as a step in the (basic) flow, allows for validating the other post-conditions of the called use case in alternate of even exceptions flows that, in this case, branch off of step 7.

image

Here the alternate flow Other Contact not selected describes what happens in that particular case. After finishing, it re-joins the basic flow in step 3. Don’t forget to add these alternate flows.

Tip. Synchronize user actions

Many use cases have a strong component of interaction with the user. In this case the user can often start many actions independent of their order. Think of starting another use case by pressing a button, starting some action by pressing a button, filling in fields on a form, submitting it, or pressing the cancel button.

The trouble with these user actions is that in general they don’t follow a specific order. This makes describing user actions in a sequence of consecutive steps a bit awkward.

I therefore recommend the following. First, create a step in the basic flow that is simply titled User action. This step is used to allows loops and trigger actual user actions in random order. All paths no return to this specific step.

image

In this example, step 3 represents this step, and is title Actor action.

Next, add the user actions that are essential for reaching the positive post-condition in the basic flow. In this example, step 5 to 7 represent such an essential user action.

And third, add all other user actions as either alternative or exception flows. All of these branch of the step right after the Actor action step. In case these flows return to the basic flow, they always return to step 3.

Tip. Put post-conditions in results

The post-conditions of a use cases can be reached in several locations. Of course, the positive post-condition is reached at the end of the basic flow, but alternative and certainly exception flows can also result in ending the use case, in which one of the post-conditions is met.

It is a good habit to note these post-conditions as results in Enterprise Architects structured specification, as shown in the alternative flow Actor clicks Cancel below.

image

We usually precede the actual post-condition (No Relationship is saved) by either OK or Cancel, to show whether or not a positive result is achieved.

Tip. Skip details in fields in forms

When the user needs to fill in a number fields on a form, it is very tempting to add details on these fields to the structured specifications, such as:

  • Label. Name of the label associated with the field.
  • Mandatory. Can the field be left empty.
  • Display format. Is the field displayed as a text box, a radio button list, a drop down list, a checkbox, a link?
  • Edit format. Does the field have a specific edit format, such as with currencies or bank accounts.
  • Validations. All kinds of field validation, such as amounts not allowed below zero, or dates not before today.

However, adding these details to the structured specifications clutters the flows. It is better to add these field details in another location, either in a user interface diagram, or  to an additional document added to the use case. Enterprise Architect uses a linked document for this means. We use a formatted template to create these linked documents.

For the flows then it is sufficient to simply add a single step that defines that the user enters the fields in the form, as in step 9 in the example below.

image

Tip. Skip details on validation

A similar approach can be used to describe validation. As said earlier validation can be part of the use case, or can be part of elements of your domain – your domain objects, value objects, enumerations, repositories, services. In the latter case, validation is already modeled and described there. There is no need to repeat these validation in your basic and alternative flows. Validation this is specific to this use case should be specified with the use case, again not in the flows, but in the conditions.

Thus, in the flows of your use case it suffices to describe that validation takes place. But, due to the fact that validation can have different outcomes, add an additional step that handles the validation results. Always not the positive result directly below the validation step, such as in step 12 below..

image

Model any other outcome either as an alternative or exception flow that branches off of the positive outcome, in this case that branch off of step 12, such in alternative flow 12a below.

image 

Tip. Check results for save and remove actions

Although with the current state of technology it appears that implementing save or remove actions on a domain object is trivial, in fact both action can end in an undesirable result. For instance, a remove from the database might fail due to the fact other records depend on the record you are deleting. A save might fail due to concurrency, or due to rules in the database failing.

So again, similar to checking the result of validations, it is good practice to also monitor the result of a save or remove actions with an additional step.

4 thoughts on “Describing (smart) use cases using Enterprise Architect 8. Part II – Use case scenarios and structured specifications

  1. Hi Sander,

    Thank you for your very insightful article into using Sparx. However, I have one question. In your article, you mention:

    “A flow does not include if-then constructs (these will be alternate or exception flows). However loop constructs can appear.”

    and

    “First, create a step in the basic flow that is simply titled User action. This step is used to allows loops and trigger actual user actions in random order. All paths no return to this specific step.”

    Now I cannot find how to create loops in Sparx structured scenario’s Basic Path anywhere on internet. I don’t mean alternates, but just normal loops in the basic path. Can you please explain how this works or why you say they can appear?

    Thanks in advance.

Comments are closed.