Broadleaf Microservices
  • v1.0.0-latest-prod

Changing Fulfillment Status

Initiating Status Change

An Order Fulfillment can have its status changed by either:

  • API call to FulfillmentOperationEndpoint

  • Internal usage of FulfillmentOperationService#changeFulfillmentStatus

    • Asynchronously from a message listener to automatically change status, ex. AbstractAutoStatusChangeListener

    • Synchronously after another operation is complete, ex. at the end of FulfillmentCapturingPaymentListener

Two types of status change are supported:

  • Complete status change

    • Changes the status of the entire fulfillment

  • Partial status change

    • Request to update only certain quantities of certain items within the fulfillment

    • Splits the existing fulfillment

    • A new Order Fulfillment with the requested items and new status is created and returned

    • The rest of the items will remain in the existing Order Fulfillment with the old status

In order for an Order Fulfillment to change to a particular status, a FulfillmentStatusChangeHandler must be registered which can update to that status. Generally these handlers define:

  1. A target status - the status they can handle moving Order Fulfillments into

  2. Valid originating statuses - the statuses they can handle moving Order Fulfillments from

For example, there’s a status CAPTURING_PAYMENT which is where payment capture occurs. A business rule dictates that we can only start capturing payment from the NEW status. So there is a CapturingPaymentStatusChangeHandler which implements FulfillmentStatusChangeHandler and can handle a target status of CAPTURING_PAYMENT and an originating status of NEW.

Processing the Status Change

Fulfillment Status Change Sequence Diagram
Figure 1. Processing of a partial Order Fulfillment status change in default implementation

  1. FulfillmentOperationService receives the request to change an Order Fulfillment’s status, FulfillmentStatusChangeRequest

  2. FulfillmentProvider reads the Order Fulfillment by ID through the OrderService

  3. FulfillmentStatusChangeValidator checks that the Order Fulfillment has enough quantity of the items for the requested status change

  4. FulfillmentOperationService searches through the FulfillmentStatusChangeHandlers for one that can handle the request

    1. Each FulfillmentStatusChangeHandler checks if it can move a fulfillment in the existing original status to the new target status

  5. FulfillmentStatusChangeHandler checks if we need to split up the fulfillment

    1. If the request didn’t specify any item quantities, or specified all the items, then we’ll just update the existing fulfillment

    2. Otherwise the FulfillmentSplittingService will split the requested items out of the existing Order Fulfillment into a new Order Fulfillment

  6. FulfillmentStatusChangeHandler updates the new Order Fulfillment to the new status (or if there was no split, updates the existing fulfillment)

  7. FulfillmentProvider saves all relevant fulfillments, split or updated, through the OrderService by replacing or creating them

  8. Most handler implementations will publish a FulfillmentStatusChangeEvent on a specialized topic (see Messaging)

  9. FulfillmentStatusChangeHandler and then FulfillmentOperationService return the fulfillment that had its status changed