Managing Workflow States

Managing State

A very common workflow pattern is Managing State.  So, in this section, we'll look at some recommended practices for Managing State.

Firstly, changing the status of an entity.

Don't change an entity's status until all conditions of that state have been confirmed. Where possible, group required rules into a single ruleset for the task. 

For example, if there is a requirement to capture a reason for canceling an order cancellation, this rule can live in the same ruleset as the state change rule.

Secondly, avoid duplicating logic within a workflow.

Don't duplicate logic unnecessarily within the workflow—this makes it harder to maintain and may result in unexpected differences in behavior between the different tasks. The workflow should be readable and simple.

Example: Avoid having more than one Change of State action for each state.

Finally, you must always use the SetState rule (from the Core Reference Module plugin) to change the state of an entity. 

Use the SetState rule to change status, as this will ensure that the workflow engine can track the state change and update the context appropriately. If any status changes are made via direct mutation, the workflow engine would not know about this change, which may result in incorrect ruleset matching logic during event execution.

Lastly, even if you are able to change the state of an entity via a mutation from another rule, it is recommended that you never do this, as it would mean that the state change logic would be hidden inside the Java code, where no one knows it exists. 

Why does this matter?

Imagine if someone else were to use that same rule and drop it into another part of the workflow; then, their workflow would change states even if it was not intended. That, in turn, might require additional time and effort to identify and resolve.

So, always use the SetState rule that's provided out-of-the-box so that the workflow engine can track and be aware of any entity state changes, ensuring the event context is valid during processing.  

Recommended Practices

• Only set the new Entity States when the State is meaningful
• Don't set the same state from multiple Rulesets
• If and where possible, handle all state logic within a single execution thread, including child actions
• Only Change State using the dedicated SetState rule, and not together with other changes in a single mutation
• Consider using more states to help alleviate any discrepancies in meaning
• Use Ruleset triggers appropriately for helping to guard against illegal actions on states
• Identify Intervention states, such as FRAUD_CHECK, PAYMENT_FAILED, UNFULFILLABLE