External (a.k.a., Actor) Guidelines

The following guidelines concerning actors have proven effective when performing use case modeling during the requirements engineering of operational requirements:

Identify the Boundary

Guidelines

• Clearly differentiate the scope of the use case model.
• Decide whether one is modeling a:
  • Business
  • System application containing data, hardware, software, and wetware (personnel) components.
  • Software application.
  • Application domain.
  • Software component.
• Be consistent regarding this boundary when identifying externals (a.k.a., actors).
• Label the boundary on relevant diagrams:
  • Context Diagrams.
  • Domain Object Diagrams.
  • Use Case Diagrams.
  • Use Case Sequence Diagrams.

Rationale

• Unless you clearly distinguish what you are modeling, it will be difficult to determine what the actors are.
• Because a system may contain different kinds of components, an external to a software application or software component may nevertheless be internal to the larger system.
• It is easy to make mistakes if the boundary is not obvious.

Summarize the Context

Guidelines

• Use one or more context diagrams to summarize the static environment of the application in terms of its actors and the relationships between it and its actors.
• Also, document all significant relationships between actors on the context diagram.
• Provide narrative English description of the context diagram that clarifies anything that is not totally obvious.
• Also, summarize the workflow between collaborating actors using activity diagrams.

Rationale

• Context diagrams help one understand the context of an application.
• Relationships between actors often make the resulting context more understandable, especially inheritance relationships or associations when the order of use cases depends on interactions between actors.
• This guideline makes it easier for domain experts and others less familiar with this diagram to understand it.
• The overall goals of the business or application are implemented by workflows that often involve multiple actors and use cases.

Example System Context Diagram:

The following system context diagram documents the digital thermostat system application, its externals (user and room), and the associative relationships between them.

Example Software Context Diagram:

The following software context diagram documents the digital thermostat software application, its direct and indirect externals (mostly hardware), and the associative relationships between them. Indirect externals are included because they include the most important externals (e.g., user, room) as well as hardware externals with which the software application must interface and control. Note that this context diagram could also be considered a system application architecture diagram because most of the externals as well as the software are components of the digital thermostat system application.

Initially Focus on Human Actors

Guidelines

• Concentrate on identifying human actors before identifying external applications, systems, databases, etc.
• Determine which groups of users need to use the application to do their jobs.
• Determine which groups of users use the application's primary functions, and which user groups (e.g., members of the customer organization) use secondary functions such as administration and operations.

Rationale

• This guideline helps identify the most important use cases first.

Initially Focus on Client Externals

Guidelines

• Concentrate on identifying actors that depend on the application rather than supporting server actors on which the application depends.
• Identify the client actors, which:
  • Make requests of the application.
  • Notify the application about events.
  • Proactively provide information to the application.

Rationale

• This guideline helps identify the most important actors and use cases first.

Document all Relevant Externals

Guidelines

• Document all relevant actors including both actors that directly interface with the application as well as actors that indirectly interface via other actors.

Rationale

• The object model often includes classes corresponding to both indirect actors and direct actors.
• Direct actors (e.g., keyboard, console) are sometimes less important than the indirect human actors that use them.

Externals Should be Cohesive

Guidelines

• Actors should have a cohesive set of goals and responsibilities.
• Every actor should not involve every use case.
• Client actors typically benefit from more than one use case, but do not benefit from more than 10-15 use cases.
• Server actors need not benefit from any use case.
• No actor typically benefits from every use case.
• Use inheritance to factor out common characteristics of actors.

Rationale

• This guideline makes actors and their resulting use cases easier to understand.

Identify External Stereotypes

Guidelines

• Categorize the externals as human roles, databases, hardware devices, software applications, and external systems.
• Differentiate these different stereotypes of externals with intuitive icons.

Rationale

• This guideline makes context diagrams and use case diagrams easier to understand and avoids confusion (e.g., when the UML stick figure is used for hardware and software externals as well as human actors).

Organize by Externals

Guidelines

• Organize the use case model into packages, first by external stereotype (e.g., human actor, hardware, software) and then by specific external (e.g., customer, user). Within a package, use a standard sort order, either alphabetically or by major system function.
• Those subordinate use cases that are not primarily associated with any one external should be grouped into a package associated with the application.

Rationale

• This guideline provides a natural organization to the use case model that is both easy to use and user-centric.
• Most use cases primarily benefit one external (often a human actor).
• Domain experts’ expertise often maps nicely to different types of externals (e.g., users vs. hardware components.

Identify Roles, Not People or Job Descriptions

Guidelines

• When identifying human actors, concentrate on roles rather than people or job descriptions.

Rationale

• Remember that human actors are roles, not persons or job titles.
• A single person may play multiple roles when interacting with an application.

Properly Name Externals

Guidelines

• Provide a unique, meaningful name to each external.
• The name should be consistent with, and implied by, the associated definition and responsibilities.
• Name human actors after the associated roles that people play when interacting with the application.
• Use the common name for legacy applications and systems.
• Watch out for unintended synonyms due to parallel development.

Rationale

• This guideline makes the resulting documentation easier to understand.
• Remember that the name of a human actor need not be a job title, because the same person may play multiple roles when interacting with the application.

Bad Example:

• Button pusher.
  (What the user of a digital thermostat does, not who the actor is.)

Better Example:

• User

Define the Externals

Guidelines

• Provide a clear, concise, glossary definition of each external.
• Ensure that this definition is consistent with the name of the external and its responsibilities.

Rationale

• Because actors need not be job titles, they may be new concepts, even to domain experts.
• Because domain experts and requirements analysts often have different undocumented definitions for the same terms, formally defining the externals helps avoid confusion.

Bad Example:

• The user is the person who presses the buttons on the digital thermostat.

Better Example:

• The user is the actor who uses the digital thermostat to control the temperature of a room.

Document Responsibilities

Guidelines

• Document the responsibilities of each actor.
• Where appropriate, include responsibilities for doing, knowing, and enforcing business rules.
• Document responsibilities rather than specific tasks or operations that implement the responsibilities.

Rationale

• An actor is largely defined in terms of its responsibilities.
• Documenting the responsibilities provides the context needed to understand and justify the associated use cases.
• An actor should have a cohesive set of responsibilities.

Bad Example:

• The following “responsibilities” of the user of a digital thermostat are at too low of a level of detail:
  • Turn on the digital thermostat.
  • Turn off the digital thermostat
  • Decrement the desired temperature of the room.
  • Increment the desired temperature of the room.

Good Example:

• The following responsibilities are above the level of abstraction of an operation:
  • Control the actual temperature of the room by:
    • Observing the display.
    • Changing the state of the digital thermostat.
    • Changing the desired temperature of the room.

Document State Behavior

Guidelines

• Document the state models of any actors having significant state.

Rationale

• This guideline clarifies use case path preconditions and postconditions.

Example:

• The air conditioner, fan, and furnace have the following state model:

No Requirements on Actors

Guidelines

• Never inadvertently specify requirements on externals.

Rationale

• The use case model specifies requirements on the blackbox business or application rather than the actorss with which it interacts.

Bad Example:

• The user shall control the temperature of the digital thermostat.

Good Example:

• The digital thermostat shall permit the user to set the desired temperature of the digital thermostat to any temperature between the minimum and maximum desired temperatures.

Identify Required Actor Expertise

Guidelines

• Identify the required expertise and training for all human actors.

Rationale

• Different users of an application require different levels of training and expertise.
• By specifying the required levels, training plans can be developed.

Example:

• An average six year old should be able to successfully use the digital thermostat with minimal (i.e., 5 minutes of) training.

Specify Required Interfaces

Guidelines

• Specify any required interfaces to the actors, especially to existing hardware devices and software applications in the external API specification.

Rationale

• This guideline ensures that the designers have adequate requirements to implement the interface across which the interactions flow.