C#DocumentationDomain driven designEnterprise Architect (Sparx)Smart use casesUMLUse cases

Describing (smart) use cases using Enterprise Architect 8. Part I – Templates and validations

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.

A use case template

The specification of the individual use cases in the model follows a template, that at least should contain:

  • Name. Every use case should have a clear descriptive name, that will in most use cases suffice to make clear what this use cases is all about. Please name use cases in active sense, most often a combination of an active verb and a noun.
  • Goal. What is it the use case should do? Can also be used for a brief description of the use case, often a first draft of the use case.
  • Pre-conditions. The set of conditions that must be met before the use case can be executed.
  • Post-conditions. The set of conditions that must be met by the use case on completion. In my opinion these can be both positive and negative condition.
  • Basic flow. A sequence of steps that describes the interaction between the actors and the system that leads to the desired result. The actors can be both the executing actor (often a person or role) as assisting actors (in many cases other systems, or services).
  • Alternative flows. Deviations from the basic path may lead to one or more alternative flows. Each alternative flow again describes a sequence of steps that starts at a certain step in either the basic flow or another alternative flow, and returns to possibly the same step, or to another step (in the same scenario), or even possibly ends the use case.

Constraints

In addition, we often model other types of constrains (next to pre- and post-conditions) with a use case:

  • Input. Parameters that are passed into the use case when the use case is started. Note: these are not preconditions.
  • Validation. With certain steps validation can occur. In most cases validation concerns the domain objects or view models that are handles by the use case. These should be modeled with the object it concerns. However, sometimes additional validation is typical for the use case at hand. These validations are modeled as constraints on the use case.

Describing use cases in Enterprise Architect

In Enterprise Architect every use case comes with a property window, which is opened for instance on double-clicking a use case in the diagram. Unfortunately this property windows is implemented as a modal window, which means it is not possible to navigate away from the window without pressing OK or Cancel. Thus it is hard to check on other diagrams or elements in the model while specifying a use case.

On the main page of the property window the use case is named. We usually use the Notes property to specify the goal of the use case. Keep this description short, as it is not intended to capture one or more of the flows in the use case. In the example below, the Notes property is clearly far too long.

SNAGHTML1736b47

Describing constraints in Enterprise Architect

We consider an number of types of constraints with a use case, as described above. Enterprise Architect allows to define your own constraint types, next to the pre-defined types, so we’ve added Input and Validation.

SNAGHTML17a43ab

The constraints for a specific use case can again be described in Enterprise Architect in the property window. We usually specify both a name and a description for each of these constraints.

SNAGHTML17dc346

In the example here, the use case has defined a pre-condition, a post-condition, requires both a valid Contact and a Relationship to be passed in (constraint type Input), and describes a number of validations (constraint type Validation).

Please note that the name for validation constraints should be clear and descriptive, as they will also appear in code, on the implemented use case, resulting in a method of the use case class, as suggested in the C# code example below.

   1: [BusinessRule]
   2: public ValidationResult OtherContactIsNotEmpty()
   3: {
   4:     return !Relationship.To.IsEmpty 
   5:         ? ValidationResult.CreateError(this.Prop(t => t.Relationship.To), "Other contact in relationship may not be empty")
   6:         : ValidationResult.Success;
   7: }

Different types of validations

When describing validations, it is vital to understand which validations are handled by the use case, and which validation are handled by the domain object or view model that is handled by the use case.

Validations on domain objects

During the execution of a particular use case the state of a domain object (or view model) might be altered, for instance due to user input, but also due to specific steps in the use case. When this happens, the domain object can be considered as dirty. This is a state where it is uncertain whether the domain object is actually valid, or that is has become invalid. Validations may now be performed on the domain object, for instance before persisting it.

Such validations may include required fields, validations properties that are value typed (think of email, zip codes, social service numbers), but can also be business rules (start date for a contract must be before the end date of a a contract). These validations are always true when the domain object is in valid state.

Modeling validations on domain objects

Such validations are best modeled and describe with the specific domain object.

image

In the example above the domain object Relationship (which is stereotyped here as business class) we have modeled different types of validations:

  • Required. The properties Description, StartDate and EndDate are not mandatory for the domain object to be valid. The multiplicity of these properties is set to [0..1] – which implies that zero or one instances of this property are present.
  • Value object. Although not visible in the example, properties may have types that are defined as value objects, such as Email or Isbn. This means that the validations rules for this particular value object will apply to this property.
  • Enumeration. In the class RelationshipType, the property To is modeled as ContactType, which is an enumeration of possible values. This enumeration is modeled elsewhere in the domain model.
  • Association. The class Relationship described three associations with other classes. The properties From and To are modeled as associations with Contact, and given the multiplicity are mandatory for an instance of Relationship to be valid.
  • Rule. Additional, we have modeled  some business rules as methods on the domain object Relationship, such as ToContactMustMatchRelationshipType(). We have use the stereotype business rule to make sure developers will implement these accordingly, such as in the code example below.
   1: [BusinessRule]
   2: public ValidationResult ToContactMustMatchRelationshipType()
   3: {
   4:     return !To.IsEmpty && RelationshipType.To != To.ContactType
   5:         ? ValidationResult.CreateError(this.Prop(r => r.To), "Contact type '{1}' for {0} does not match required contact type '{2}'.", To, To.ContactType, RelationshipType.To) 
   6:         : ValidationResult.Success;
   7: }

Validations on use cases

With some use cases validations may occur during the execution of the use case steps. Such validations will validate the correct behavior of the use case, and are not specific to the domain objects that are handled by the use case.

A good example would be a use case Change Password, where the user has to enter his old password for his Account, and twice a new password. Typically, Password is a property of the domain object Account. But entering a new password twice is only temporary and checking whether the first entered new password matches the second entered new password does not validate the state of the attached Account object.

Therefore both new passwords are not modeled and implemented as properties on Account, but rather it’s the use case’s responsibility to validate equality on the new passwords. It’s only after these appear to match, and the the entered old password matches the Password property of the Account object, that this property gets sets, the Account object is validated and saved.

Modeling validations on use cases

Such validations can be modeled in Enterprise Architect in the property window of the use case.

SNAGHTMLa5bcfb

Use the (custom) constraint type Validation. Give the validation a name that will match the name of the method on the use case in code to guarantee traceability. Also write a undisputable description for the validation.

Part II of this post will deal with writing use case scenarios, basic flows, alternative and exception flows using structured specifications in Enterprise Architect.

2 thoughts on “Describing (smart) use cases using Enterprise Architect 8. Part I – Templates and validations

  1. without a doubt one of the best written articles on enterprise architecture, specially the part explaining the different types of validations…coupled with nice pictures you have and awesome post here..kudos to you

  2. Hello! Your article is very interesting, I’m used to EA for a couple of years. I’m on Brasilia, Brazil. A System Architect is suggesting to use Enterprise Architect to describe even Uses Cases text, but i’m reluctant, as client, that this approach is so hard to maintain, and to be sure that system analysts will follow in a correct way. Whats your opinion about?

    Thanks in advance.

    Érica

Comments are closed.