Best practices for working with Composable Commerce States.
After completing this page, you should be able to:
- Understand and apply best practices for designing and implementing States in Composable Commerce.
Let's dig into some of the best practices for using state machines in Composable Commerce.
Make changes to existing States
When modifying States that are being actively used by resources (for example, Orders or Payments), it's crucial to consider the impact on existing resources. Existing States can’t be deleted or changed if a resource has that State assigned. This means that you will need to migrate the resource to the new State before making either of those changes to the existing State.
Here are a few best practices to follow:
- Plan carefully: before implementing any changes, thoroughly analyze the potential impact on resources in different States.
- Versioning: consider creating new States instead of directly modifying existing ones, especially for significant changes. This allows for a gradual transition.
- Testing: thoroughly test State transitions and actions in a staging environment before deploying changes to production.
Hide default system State fields in Merchant Center
The Merchant Center displays default system State fields such as TransactionState, OrderState, and ShipmentState. These fields are not customizable. If you're using custom States, then you might want to hide these default fields to avoid confusion.
How to hide default fields
An administrator can configure the Merchant Center to hide the default dropdown for Order Status, Shipment Status, and Payment Status. You can find this option under Project Settings → Miscellaneous.
Important note: Hiding these fields in the Merchant Center only affects the UI. The default system State fields will still exist and can be accessed by using the API.
Use descriptive State keys and names
Choose keys and names that reflect the business meaning of the State. Avoid generic names such as "State1" and "State2." Instead, use names such as "OrderCreated," "PaymentAuthorized," "PartiallyShipped," and "FullyReturned."
In addition, use a consistent naming convention; for example, PascalCase or camelCase.
Define transitions explicitly
Always try to define transitions between States, even if it seems like any transition is possible. This enforces data integrity and prevents accidental or invalid State changes. Relying on the no transitions-defined behavior (which allows any transition) is discouraged.
Document the meaning and purpose of each transition. You can do so with the Description field.
Handle all possible transitions
Make sure that your application code handles all possible State transitions, including error conditions. Don't assume that a transition will always succeed.
Plan for the evolution of state machines
Anticipate that your business processes will evolve over time. Design your state machines with flexibility in mind.
Use a versioning strategy for your state machines (for example, by creating new States with updated keys) to manage changes without disrupting existing resources.
When adding new States or transitions, carefully consider the impact on existing resources that are already in a particular State. You might need to migrate existing resources to new States.
Test thoroughly
Write unit tests to verify that your State transitions and actions work as expected.
Test edge cases and error conditions.
Use a staging environment to test changes before deploying them to production.
Document your state machines
Create clear and up-to-date documentation for your state machines, including diagrams, State descriptions, transition rules, and action details. This is crucial to help ensure maintainability and collaboration.
By following these best practices, you can create robust, maintainable, and scalable state machines in Composable Commerce that accurately reflect your business processes and ensure data consistency.