You can use OnStateChange on a class to react to every state-machine trigger call for that class, primarily for shared audit and logging behavior.
Use OnStateChange for state-change auditing
Define a method with this exact signature:
OnStateChange(attrib:String; oldstate:String; newstate:String)
Any class that has a method with this signature receives a call for each trigger call made on a state machine. If the class has multiple state machines, state changes from all of them are routed through this method.
Use this method when you need one common place to record or react to state changes, rather than repeating equivalent logging behavior in each individual state machine.
= Parameters
| Parameter | Type | Purpose |
|---|---|---|
attrib
|
String
|
The attribute value supplied by the state-machine change call. |
oldstate
|
String
|
The state before the trigger call. |
newstate
|
String
|
The state after the trigger call. |
For example, when a trigger changes an object's state from Pending to Approved, the method receives oldstate as Pending and newstate as Approved. Your method can use those values to record that change in the class's audit logic.
Add the method
- In MDriven Designer, open the class on which you want to handle state-machine changes.
- Add a method named
OnStateChange. - Give it the three parameters
attrib:String,oldstate:String, andnewstate:String, in that order. - Put the audit or logging behavior in the method body.
- Exercise a state-machine trigger and verify that the method receives the previous and new state values.
If the class contains more than one state machine, keep the handling generic enough to process calls from each of them. The attrib, oldstate, and newstate arguments let the method record the context supplied for each call.
Do not use this method to block a transition
OnStateChange is not a transition-validation mechanism. Do not use it to decide whether a state-machine transition may occur. Use a state-machine guard when a business rule must prevent a transition.
For example, if an order must not move to Approved until required information is present, implement that rule as a guard. Use OnStateChange to record that the transition was requested or completed, not to stop it.
Choose the right place for the behavior
| Need | Put the behavior here |
|---|---|
| One audit or logging implementation for changes from multiple state machines on the same class | OnStateChange
|
| Behavior specific to one state or one transition | A state effect or entry action in that state machine |
| A rule that must prevent a transition | A state-machine guard |
State effects and entry actions can also implement logging. Prefer OnStateChange when the logging is generic and should be kept outside the individual state-machine definitions.
Related object lifecycle methods
OnStateChange handles state-machine trigger calls. It is separate from lifecycle methods that run when an object is created, saved, or deleted:
- OnCreate runs after a new object has been created.
- OnUpdate runs immediately before an object is saved to the database.
- OnDelete runs when an object is deleted.