You can use a State Diagram in MDriven Designer to define the allowed lifecycle states and state changes for instances of a class, such as a House moving from Plan to Construction.

What a State Diagram models

A State Diagram (also called a state machine diagram) describes the states an object can be in and the transitions that move it between those states. Use it when a class has a lifecycle with meaningful phases, rules, or actions.

For example, a House can move through these states:

• Plan
• Construction
• Maintenance
• Demolition

The State Diagram belongs to a class through its State attribute. The State attribute is marked with an S icon when the state-diagram symbol is available.

State Diagrams are one of the diagram types available in MDriven Designer. For the role of class and process diagrams, see Documentation:MDriven designer overview Part 1 and Documentation:Class diagrams.

Create and open a StateMachine

1. In MDriven Designer, add a StateMachine for the class whose lifecycle you want to model.
2. MDriven Designer opens the new StateMachine when it is created.
3. Return to the class diagram using the back navigation. The class now has a State attribute that is a state attribute.
4. Open the diagram again by selecting Show state diagram for the State attribute, or by opening the StateMachine from the repository tree.

For example, adding a StateMachine to House creates the state attribute House.State. In the State Diagram, the Property Inspector identifies the state attribute as State in House.State. You can change the state attribute name, category, and color used for new states in the Property Inspector.

Build a lifecycle

Create states that reflect the business situation of the object, then connect them with transitions.

For a House lifecycle, define the following progression:

State	Meaning	Example transition into the state
Plan	The House is planned but construction has not started.	The initial state reaches Plan when no guard prevents it.
Construction	The House is being built.	StartConstruction
Maintenance	The House is in use and maintained.	ConstructionDone
Demolition	The House has reached its demolition phase.	Demolish

1. Add the states to the State Diagram.
2. Create a transition from the initial state to Plan.
3. Create a transition from Plan to Construction and give it the trigger StartConstruction.
4. Create a transition from Construction to Maintenance with the trigger ConstructionDone.
5. Create a transition to Demolition with the trigger Demolish.

A trigger is the named event that takes an object from one state to another. Reuse a trigger name when it represents the same event. For example, a car can use InitiateSale both when it first enters an ownership transaction and when a later owner starts a new transaction.

Add nested steps with regions

Use a region when one state contains its own internal lifecycle. A region lets you show sub-states without expanding the top-level lifecycle into many separate states.

For example, Construction can contain a region with these sub-states:

1. Add a region to Construction.
2. Set GroundWork as the region's initial sub-state.
3. Add Building.
4. Add a transition from GroundWork to Building with the trigger StartBuilding.
5. Keep the top-level transition ConstructionDone to move the House from Construction to Maintenance.

When a House enters Construction, it enters the region at GroundWork. The internal trigger StartBuilding then moves it to Building.

Control transitions with guards

A guard is a domain rule that must be fulfilled before a transition can occur. Add guards when an event alone is not enough to permit a state change.

For example, an ownership transaction can be prevented from closing until the buyer is known. Model the transition to the closed state with a guard that verifies the required information. This makes the rule visible in the lifecycle rather than leaving it implicit.

Use OCL for expressions that evaluate domain rules and actions in the model.

Run an action when a state is entered

An entry action is an action performed whenever an object enters a state. Use it for required side effects of entering that state.

For example, when a Car enters InOwnershipTransaction, create and attach a transfer document, then set its seller from the current owner:

let doc = CarTransferOwnershipDocument.create in
  self.CarTransferOwnershipDocuments.add(doc);
  doc.Seller = self.CarOwner

In this example, self is the Car entering the state. The entry action creates a CarTransferOwnershipDocument, adds it to the Car's transfer-document association, and records the current owner as seller. The buyer can be supplied later; a guard can prevent the sale from closing before that information exists.

Keep entry actions focused on effects that must happen every time the state is entered. Put the condition for whether a transition is allowed in a guard.

Show the State attribute icon

If the class diagram does not show the State attribute as a state attribute, ensure that the default TagExtensions are available.

1. Open the TagExtensions dialog from the functions area.
2. Ensure these default TagExtensions are present:
   • statediagramsymbol
   • triggermethod
   • constraintclass
3. Return to the class diagram and inspect the State attribute. The state-diagram marker is shown as an S icon.

The TagExtensions use WPF XAML definitions. This makes it possible to define another symbol by providing the XAML for the symbol you want to display. Use custom symbols consistently so that diagrams remain understandable to other modelers.

Design guidance

• Name states after stable business situations, such as Maintenance, rather than after a UI operation.
• Name triggers after the event that causes the change, such as StartConstruction or Demolish.
• Use a region when a state has meaningful internal phases, such as GroundWork and Building within Construction.
• Use guards for rules that must hold before leaving or entering a state.
• Use entry actions for side effects that must occur when a state is entered.
• Keep the State Diagram focused on one lifecycle. You can use diagrams as navigation and documentation aids without duplicating model elements; see Documentation:Diagrams in Diagrams.

See also

• Documentation:OCL Editor, system prototyper and ViewModel
• Documentation:State value as a string
• Documentation:Class diagrams
• Documentation:Diagrams in Diagrams
• Documentation:Autodiagram