You use a StateMachine attribute to define the permitted lifecycle states for objects in a class and the allowed paths between those states.
Contents
Model a controlled lifecycle
A StateMachine attribute is a special attribute on a class. Its value is represented by a state diagram. The states in that diagram are the only allowed string values for the attribute.
For example, an Order class may have a StateMachine attribute named Status with these states:
DraftSubmittedApprovedCancelled
An Order can then have Status set to Draft, but it cannot have an undefined value such as WaitingForReview unless that state has been added to the state diagram.
Define allowed changes
The state diagram also defines the transitions between states. A transition is an allowed change from one state to another.
In the order example, you can define transitions such as:
DrafttoSubmittedSubmittedtoApprovedDrafttoCancelledSubmittedtoCancelled
If there is no transition from Approved back to Draft, that change is not allowed. This lets you model the order in which work must progress instead of relying on unrestricted text values.
Add guards to transitions
A guard is a rule that must be true before a transition is allowed. Use guards when the transition depends on information held by the object or its related objects.
For example, a transition from Submitted to Approved can require that the order has the information needed for approval. If the guard is not fulfilled, the object remains in Submitted.
Use OCL when you need to express such rules. Keep a guard focused on whether the change is allowed; use the state behavior described below for work that should happen after the change.
Define behavior on state entry
You can define things that happen when an object enters a state. This is useful when reaching a state should trigger a defined piece of behavior.
For example, entering Approved can perform the behavior associated with approval. Keeping that behavior on the state makes the lifecycle rule visible in the same diagram as the permitted transitions.
State names are unique within a class
A class can have more than one StateMachine attribute. For example, an Order might have both Status and PaymentStatus.
Each state name must be unique within that class, even when the states belong to different StateMachine attributes. This enables an object-level OCL check that does not need to name the attribute:
self.oclIsInState(#Approved)In this example, Approved must identify one state only on the class. Do not use Approved in both Status and PaymentStatus for the same class.
When to use a StateMachine attribute
Use a StateMachine attribute when a value represents a lifecycle with controlled steps. It is a good fit for values such as an order status, review status, or approval status.
Use a regular attribute when the value is not a controlled lifecycle. See MDrivenStart:MDrivenStart Attributes for general attributes and MDrivenStart:MDrivenStart DefineInformation for how classes, attributes, associations, and StateMachine attributes fit into the information model.
Verify the model
After changing the state diagram, verify the model before you prototype or deploy it.
- Save the model. Validation runs automatically when you save.
- You can also run validation manually with the Validation button.
- Resolve all validation errors before starting the Prototyper or deploying to the server.
See MDrivenStart:MDrivenStart Verify for the verification workflow.