State machines

State machines, also known as finite state machines (FSMs), are a powerful design pattern for modeling systems with discrete, event-driven behavior. They define how a system transitions between a finite set of States based on specific inputs or events.

In Composable Commerce, States are a crucial feature for managing the lifecycle and workflows of various resources such as Orders, Payments, Carts, and Products. Using state machines helps ensure data consistency and simplifies complex workflows.

A state machine typically contains the following items:

• States: a finite set of distinct conditions representing the possible stages of a system. For example, an Order might have States such as Pending, Confirmed, Shipped, or Completed. Each State represents a meaningful stage in the resource's lifecycle.
• Transitions: rules that dictate how the system moves from one State to another. Transitions are triggered by either inputs or events. A transition defines the allowed State changes.
• Inputs/Events: external actions or data that trigger a State transition. In an e-commerce context, this could either be payment captured, item packed, shipment created, or customer cancelled. Inputs or events are often asynchronous events.
• Actions: operations that are performed either during a transition, on entering a State, or upon leaving a State. Actions can include sending notifications, updating Inventory, calling external services (for example, a payment gateway), or updating related resources. Actions are the side effects of a State change.
• Initial State: the default starting State of the system. Every resource managed by a state machine begins in this State.

Key benefits of using state machines

• Explicit workflow definition: state machines make the flow of your business processes visually clear and easy to understand.
• Data consistency: by enforcing valid transitions, state machines prevent invalid State changes, ensuring data integrity.
• Reduced complexity: state machines break down complex workflows into manageable and distinct steps.
• Improved testability: each State and transition can be tested independently.
• Auditable: the history of State transitions provides a clear audit trail of the resource's lifecycle (requires Audit Log Premium).
• Extensibility: adding new States or transitions is often easier and less error-prone than modifying complex conditional logic.

How state machines work - Conceptual flow

1. The system (for example, an Order) begins in its initial State.
2. An input is received or an event occurs (for example, a webhook from a payment provider).
3. The state machine then evaluates the current State and input/event.
4. Based on predefined transition rules, the state machine determines the next State. If no valid transition is found for the current State and input, then the State remains unchanged (and an error might be logged).
5. If a valid transition exists, then the system moves to a new State.
6. Actions (if defined) are performed:
   • Transition actions: performed during the State change.
   • Entry actions: performed after entering the new State.
   • Exit actions: performed before leaving the old State.
7. This process repeats as the system receives further inputs and transitions between States.

Let's analyze how this might play out with an example focusing on Order fulfillment.

1. Initial State: Pending (A): the Order starts in a Pending state. This is when the Order is created, but no payment has been processed yet.
2. Payment Captured? (B): this is a decision point based on an external event. The system waits for a Payment Captured event such as a webhook from the payment gateway.
3. Confirmed (C): if the payment is captured (Yes from B), then the Order transitions to a Confirmed State. Action: A confirmation email might be sent to the customer (entry action).
4. Item Packed? (D): another decision point, waiting for an Item Packed event (for example, from a warehouse management system).
5. Shipped (E): if the items are packed (Yes from D), then the Order transitions to a Shipped State. Actions: Inventory might be updated (transition action) and shipping notifications could be sent (entry action).
6. Shipment Created? (F): waiting for a Shipment Created event (for example, from a shipping carrier integration).
7. Completed (G): if the shipment is created (Yes from F), then the Order transitions to a Completed State. This signifies the end of the Order fulfillment process. Action: Mark the Order as complete in related systems (entry action).
8. Loops (B, D, F): the No paths represent the system waiting for the required event. The Order remains in its current State until the condition becomes true. For example, the Order stays in a Confirmed State until the Item Packed event occurs.

State machines in Composable Commerce

Composable Commerce provides a flexible and customizable implementation of state machines. You can define the States and transitions that are relevant to your business processes. Your application is responsible for:

• Defining States: creates the necessary States in your project.
• Defining transitions: specifies which State transitions are allowed.
• Triggering transitions: by using the Composable Commerce API to update the State of a resource when a corresponding event occurs.
• Implementing actions: your code is responsible for implementing any actions.

Example - Payment Captured Event Handling

1. Webhook received: your application receives a webhook from the payment gateway, indicating that a payment has been captured. The webhook payload includes the orderId and paymentId parameters.
2. API call to Composable Commerce: your application uses the Composable Commerce API to update the State of the Order with the given orderId. The new State is set as Confirmed.
3. State transition: Composable Commerce validates the transition, ensuring that the change of State from Pending to Confirmed is allowed. If valid, then the Order's State is updated.
4. Action execution: your application performs any actions that are associated with the Confirmed State; for example, sending a confirmation email to a customer.

Key considerations

• Error handling: implement robust error handling for cases where a State transition fails; for example, due to either an invalid transition or an API error.
• Asynchronous events: State transitions are often triggered by asynchronous events. Design your system to handle these events in a reliable manner.
• Idempotency: make sure that your event handlers are idempotent. If the same event is received multiple times, then it should result in only a single State transition.

Resources that support state machines

Composable Commerce offers the following resources for state machines:

• Orders
  • LineItems
  • CustomLineItems
• Payments
• Products
• Reviews
• Quote Requests
• Quotes
• Staged Quotes

When setting up state machines, make sure to consider:

• Default initial State: each project has a default initial State for LineItems. You can update this default State, except for its key.
• State assignment: after creating a resource, you can assign it a State via a transition update action by using the API.
• State reusability: a single State can be used by multiple resources.
• Transition flexibility: each State can have multiple possible transitions to other States (one-to-many and many-to-one relationships).
• Optional transitions: defining transitions is optional. If transitions are not defined, then a State can transition to any other State of the same resource type.

Example - LineItem state machine

Here's a simple example of a state machine for Order Line Items, illustrated by using a State diagram.

The diagram shows the following:

• States: Pending, Picked, Packed, and Shipped
• Events (inputs): item_picked, item_packed, and handed_to_courier
• Transitions: the arrows indicate the valid transitions between States based on the events.