You can repair an object whose state is incorrect and cannot reach the required state through defined transitions; this guidance is for developers maintaining MDriven StateMachines.
Keep state-machine rules as the normal path
A state machine restricts a state attribute to its defined state values and transitions. A transition can also require a guard to be true before the object may move forward. For example, an object designed to move from State1 to State2 and then State3 cannot normally move directly from State1 to State3.
Use transitions and guards for ordinary business operations. They keep the object lifecycle explicit and prevent application code from treating a state attribute as an unrestricted string. For an introduction to state attributes, states, transitions, and guards, see MDrivenStart:MDrivenStart StateMachines.
When force mode is appropriate
Use stateMachineForceMode only when an existing object is in the wrong state and there is no legal transition to the state it should have. Typical causes include:
- A state-machine design was corrected after objects were already stored.
- A defect or incorrect business interpretation placed an object in a state that must be repaired.
- An object was accidentally moved to a terminal state, such as
Discarded, and the current model has no transition that can restore it.
Force mode is an elevation for exceptional repair work, not an alternative way to implement normal state changes. If users must regularly move between two states, model an explicit transition and its guards instead.
Do not update the database directly
Do not repair a state by writing the state attribute directly in the database. That bypasses the framework and can cause important operational gaps when MDrivenServer uses Slave or HistorySlave configurations:
- The change is not recorded in the
MDrivenServerSynktable and therefore does not propagate to slaves. - The change is not recorded with a timestamp in a HistorySlave.
Perform the repair through the framework so that the normal MDrivenServer handling applies.
Force one state write
stateMachineForceMode is an OCL operation on the object. Call it immediately before assigning the state attribute.
The argument is the name of the state attribute, not the name of the state you want to enter.
For example, if the state attribute is named State and the required repair is to set it to State3:
self.stateMachineForceMode('State');
self.State := 'State3'This grants one free write to that state attribute. The next assignment is forced; later assignments again follow the state-machine rules.
One-write limit
The following fails on the second assignment because the free pass has already been consumed:
self.stateMachineForceMode('State');
self.State := 'State3';
self.State := 'State3'Request force mode again for every assignment that must bypass the rules:
self.stateMachineForceMode('State');
self.State := 'State3';
self.stateMachineForceMode('State');
self.State := 'State3'Choose the right operation
| Need | Use | Example |
|---|---|---|
| Move through a permitted named transition | The state machine's normal transition mechanism | Move an order from Approved to Shipped when its guard permits it.
|
| Re-evaluate guards and take a transition that is currently possible | stateMachineTrigger | After setting required data, call self.stateMachineTrigger so the object can follow a guard-driven path.
|
| Correct an object that cannot legally reach its required state | stateMachineForceMode followed by one state assignment | Restore an incorrectly discarded object to the required state during a controlled repair. |
stateMachineTrigger does not bypass the state machine. It asks the object to re-evaluate transitions and guards from its current state. Use force mode only when that normal evaluation cannot produce the required correction.
Safe repair procedure
- Identify the object, its current state, and the state it must have according to the corrected business decision.
- Check whether an existing transition can perform the move. If the correct transition is blocked by missing or incorrect business data, correct that data and use the normal transition or stateMachineTrigger.
- If no legal transition exists, execute
stateMachineForceModewith the state attribute name. - Assign the required state as the immediately following write.
- Verify the object after the repair, including any state-dependent behavior that the application exposes.
- Correct the state-machine model if this repair reveals a missing legitimate business path. Do not make force mode part of an end-user workflow.
Auditing state changes
For state changes that matter to your business, implement OnStateChange for audit or logging. This event method is intended for recording state changes; use guards, not OnStateChange, to prevent a transition.