Refreshing Orders

In ATG Commerce, the purchase process controls the refreshing of Orders.

When an Order is loaded from the Order Repository, the loadOrder() method in the OrderManager calls into the PipelineManager to execute the loadOrder pipeline, which creates and loads the Order object, as well as its OrderPriceInfo and TaxPriceInfo objects. (See Loading Orders above for details.) Later, when an Order property is accessed (for example, by calling getCommerceItems() or getPriceInfo()), the refreshOrder pipeline is invoked, which creates and loads the rest of the contained objects in the Order.

The refreshOrder pipeline is called only when the Order is first accessed and subsequently when an Order is invalidated and, therefore, needs to be reloaded from the Order Repository.

The following table describes the individual processors in the refreshOrder pipeline. They are listed in order of execution.

PipelineLink name	Description
`loadOrderObjectForRefresh`	Given an `Order` object supplied by the `PipelineManager`, this processor reloads its properties from the Order Repository. The `atg.commerce.order.processor.ProcLoadOrderObject` class implements this functionality.
`loadCommerceItemObjects`	Creates `CommerceItem` objects for the `Order` and loads the properties for those `CommerceItem` objects from the Order Repository. The `atg.commerce.order.processor.ProcLoadCommerceItemObjects` class implements this functionality.
`loadShippingGroupObjects`	Creates `ShippingGroup` objects for the `Order` and loads the properties for those `ShippingGroup` objects from the Order Repository. The `atg.commerce.order.processor.ProcLoadShippingGroupObjects` class implements this functionality.
`loadHandlingInstructionObjects`	Creates `HandlingInstruction` objects for the `ShippingGroups` in the `Order` and loads the properties for those `HandlingInstruction` objects from the Order Repository. The `atg.commerce.order.processor.ProcLoadHandlingInstructionObjects` class implements this functionality.
`loadPaymentGroupObjects`	Creates `PaymentGroup` objects for the `Order` and loads the properties for those `PaymentGroup` objects from the Order Repository. The `atg.commerce.order.processor.ProcLoadPaymentGroupObjects` class implements this functionality.
`loadPaymentStatusObjects`	Creates `PaymentStatus` objects for all the payment groups in the `Order` and loads the properties for those `PaymentStatus` objects from the Order Repository. The `atg.commerce.order.processor.ProcLoadPaymentStatusObjects` class implements this functionality.
`loadRelationshipObjects`	Creates `Relationship` objects for the `Order` and loads the properties for those `Relationship` objects from the Order Repository. The `atg.commerce.order.processor.ProcLoadRelationshipObjects` class implements this functionality.
`loadPriceInfoObjects`	Reloads the `OrderPriceInfo` and `TaxPriceInfo` objects in the given `Order`. Also creates the rest of the `AmountInfo` objects for the `Order`, such as the `ItemPriceInfo` objects in the `CommerceItems` and the `ShippingPriceInfo` objects in the `ShippingGroups`, and loads their properties from the Order Repository. For more information about `AmountInfo` objects, see the Using and Extending Pricing Services chapter. The `atg.commerce.order.processor.ProcLoadPriceInfoObjects` class implements this functionality.
`setCatalogRefs`	Sets the `catalogRef` property in the `AuxiliaryData` object of each `CommerceItem` in the `Order`. This processor looks up the catalog reference in the Catalog Repository using the `catalogRefId` in the `CommerceItem`. Note that, if `SetCatalogRefs.substituteRemovedSku` is true, this processor replaces all deleted SKUs in the `Order` with the “dummy” SKU defined by `SetCatalogRefs.substituteDeletedSkuId`. For more information, see Managing Orders that Contain Deleted Products and SKUs below. The `atg.commerce.order.processor.ProcSetCatalogRefs` class implements this functionality.
`setProductRefs`	Sets the `productRef` property in the `AuxiliaryData` object of each `CommerceItem` in the `Order`. This processor looks up the catalog reference in the Catalog Repository using the `productRefId` in the `AuxiliaryData` object. Note that, if `SetProductRefs.substituteRemovedProduct` is true, this processor replaces all deleted products in the `Order` with the “dummy” product defined by `SetProductRefs.substituteDeletedProductId`. For more information, see Managing Orders that Contain Deleted Products and SKUs below. The `atg.commerce.order.processor.ProcSetProductRefs` class implements this functionality.
`removeExpiredCommerceItems`	Used in conjunction with `SetCatalogRefs` and `SetProductRefs`. If the state of the `Order` is one that is defined in `RemoveExpiredCommerceItems.openOrderStates`, this processor removes from the `Order` any `CommerceItem` that contains a “dummy” SKU or product that was substituted by `SetCatalogRefs` or `SetProductRefs`. A “dummy” SKU is automatically removed. A “dummy” product is removed only if `RemoveExpiredCommerceItems.removeItemsWithDeletedProducts` is set to true; the default is true. For more information, see Managing Orders that Contain Deleted Products and SKUs below. The `atg.commerce.order.processor.ProcRemoveExpiredCommerceItems` class implements this functionality.

For more information about pipelines, the PipelineManager, and the transactional modes and transitions of the processors in the refreshOrder pipeline, see the Commerce Processor Chains section.

Managing Orders that Contain Deleted Products and SKUs

As described in the previous section, Refreshing Orders, the last three processors in the refreshOrder pipeline can be used to operate on the commerce items in an order that refer to products and/or SKUs that have been deleted from the catalog. If your catalog administrators delete products and/or SKUs in the ongoing management of the product catalog, you should configure these processors to handle affected orders appropriately. Note:If you’re running the Customer Service Module, this is particularly important because the Customer Service Module cannot display orders that contain deleted products or SKUs.

To configure the refreshOrder pipeline to manage deleted SKUs, do the following:

Create a new SKU in the product catalog. In an Order, this “dummy” SKU will be substituted for any SKU that has been deleted from the catalog.
If you’re using custom catalogs, make sure to add a “dummy” SKU to all existing catalogs.
Set the SetCatalogRefs.substituteDeletedSkuId property to the ID of the dummy SKU you created in step 1.
Set the SetCatalogRefs.substituteRemovedSku property to true. If this property is true, the processor replaces any deleted SKU found in the Order with the SKU defined in the substituteDeletedSkuId property.
If the Order is in an open state, all dummy SKUs in the Order are removed automatically by a later processor in the refreshOrder pipeline, RemoveExpiredCommerceItems. See RemoveExpiredCommerceItems in the table above for more information.

To configure the refreshOrder pipeline to manage deleted products, do the following:

Create a new product in the product catalog. In an Order, this “dummy” product will be substituted for any product that has been deleted from the catalog.
Note: If you’re using custom catalogs, make sure to add a “dummy” product to all existing catalogs.
Set the SetCatalogRefs.substituteDeletedProductId property to the ID of the dummy product you created in step 1.
Set the SetProductRefs.substituteRemovedProduct property to true. If this property is true, the processor replaces any deleted product found in the Order with the product defined in the substituteDeletedProductId property.
If you want all dummy products in an Order (in an open state) to be removed later on in the refreshOrder pipeline by the RemoveExpiredCommerceItems processor, set its removeItemsWithDeletedProducts property to true. (See RemoveExpiredCommerceItems in the table above for more information.)

It’s important to note that deleting products and SKUs is not recommended because of its impact on customers’ order histories. Site pages that render order histories typically draw order information (descriptions, media, and so on) from product and SKU repository items. If those items are deleted, order histories cannot be rendered accurately.

If you need to remove products and SKUs from your database (for example, because of a high turnover rate), you should implement a strategy that addresses its impact on order histories. Possible strategies include:

Storing the relevant description information in the CommerceItem. Note that this will cause a significant duplication of information across multiple items.
Removing all historical orders that contain products or SKUs that have been removed.
Keeping all historical orders that contain products or SKUs that have been removed. These orders will display description information for the “dummy” SKUs and products instead of for the actual items that were purchased.

ATG Commerce Programming Guide

Refreshing Orders

Managing Orders that Contain Deleted Products and SKUs