After an Order
has been created, the next step is to add CommerceItems
and possibly additional ShippingGroups
and PaymentGroups
. Creating these objects follows the same pattern as creating Orders
. First, call create
ObjectType
()
in the appropriate manager class, for example, CommerceItemManager.createCommerceItem()
. The call returns the type of class specified by the objectType
parameter, or the default type when the method used does not accept that parameter.
After creating the objects, use the following methods to add them to the Order
:
CommerceItemManager.addItemToOrder()
ShippingGroupManager.addShippingGroupToOrder()
PaymentGroupManager.addPaymentGroupToOrder()
These methods take an Order
and their respective object type as parameters. For PaymentGroups
, the order in which they are added to the Order
determines their precedence.
For more information on creating these commerce objects and adding them to an order, refer to the following subsections:
Creating a Standard Commerce Item
Follow these steps to create a new CommerceItem
and associate it with an Order
:
Call
CommerceItemManager.createCommerceItem()
.Make any changes to the
CommerceItem
, such as setting the quantity.Call
CommerceItemManager.addItemToOrder(pOrder, pCommerceItem)
to add theCommerceItem
to theOrder
.
Refer to the following example:
// Get a reference to the OrderManager OrderManager orderManager = (OrderManager) request.resolveName("/atg/commerce/order/OrderManager"); // Create the CommerceItem CommerceItem commerceItem = commerceItemManager.createCommerceItem(pCatalogRefId); commerceItem.setQuantity(3); // Add the CommerceItem to the Order commereceItemManager.addItemToOrder(pOrder, commerceItem);
Note: createCommerceItem()
will work even if you pass it a nonexistent catalog reference ID. This allows you to use Oracle ATG Web Commerce as an ordering system with multiple catalogs, some of which may not have repositories. If you want to prevent this behavior, you must institute a check.
CommerceItem
objects can include an auxiliary data construct. This structure allows you to store arbitrary data with a CommerceItem
. Examples of auxiliary data could include size and color options for a CommerceItem
. If your system includes remote components, auxiliary data can be serialized at any time; however, when defining AuxiliaryData
objects, the classes must be defined as serializable.
By default, the class includes ProductID
, ProductRef
, PropertyValue
, and CatalogRef
properties.
Creating Commerce Items in a Multisite Environment
If you are using Oracle ATG Web Commerce in a multisite-enabled installation, some additional methods and tools for manipulating Commerce items may be useful.
Follow these steps to create a new CommerceItem
and associate it with an Order
in a multisite setting:
Call
CommerceItemManager.createCommerceItem(…, …, pSiteId)
.The
createCommerceItem()
method is overloaded in the Oracle ATG Web Commerce API. One version is intended for use with Oracle ATG Web Commerce’s multisite feature, and includes apSiteId
parameter. If thesiteId
is null but multisite is in use, the method retrieves the ID fromSiteContextManager.getCurrentSiteId
.Make any changes to the
CommerceItem
, such as setting the quantity.Call
CommerceItemManager.addItemToOrder(pOrder, pCommerceItem)
to add theCommerceItem
to theOrder
.In a multisite setting, the
addItemToOrder()
method and the relatedaddAsSeparateItemToOrder()
method use thevalidateSiteCompatibility()
method to ensure that the item can be added to the order. If the item’ssiteId
is not null, thatsiteId
is added to the order’ssiteId
. If the order’screationSiteId
is null, the item’ssiteId
is copied there as well.The
validateSiteCompatibility()
check is also used when creating configurable Commerce items (see Creating a Configurable Commerce Item).
Refer to the following example:
// Get a reference to the OrderManager OrderManager orderManager = (OrderManager) request.resolveName("/atg/commerce/order/OrderManager"); // Create the CommerceItem CommerceItem commerceItem = commerceItemManager.createCommerceItem(pCatalogRefId); commerceItem.setQuantity(3); // Add the CommerceItem to the Order commereceItemManager.addItemToOrder(pOrder, commerceItem);
Auxiliary data holds the siteId
property in a multisite-enabled configuration; you can access this property at item.auxiliaryData.siteId
.
Creating a Configurable Commerce Item
Configurable commerce items are items with other items as optional components, and are described in the Using and Extending the Product Catalog chapter of this manual.
Follow these steps to create a ConfigurableCommerceItem
and associate it with an Order
:
Call
CommerceItemManager.createCommerceItem()
to create the base commerce item.Call
CommerceItemManager.addSubItemToConfigurableItem()
oraddAsSeparateSubItemToConfigurableItem()
to add options to the base item.Note: If you are using Oracle ATG Web Commerce’s multisite feature, these methods check to ensure that the item can be added to the customer’s cart (if more than one site is involved, the sites must share their shopping cart). See Creating Commerce Items in a Multisite Environment for details.
The example below illustrates how to programmatically create a ConfigurableCommerceItem
with subSKU items and then add it to an Order
:
ConfigurableCommerceItem configurableItem = (ConfigurableCommerceItem) getCommerceItemManager().createCommerceItem("configurableCommerceItem", "sku10001", null, "prod10001", null, 1, null, null, new ItemPriceInfo()); SubSkuCommerceItem subskuItem = (SubSkuCommerceItem) getCommerceItemManager().createCommerceItem("subSkuCommerceItem", "sku20001", null, "prod20001", null, 1, null, null, new ItemPriceInfo()); getCommerceItemManager().addSubItemToConfigurableItem(configurableItem, subskuItem); subskuItem = (SubSkuCommerceItem) getCommerceItemManager().createCommerceItem("subSkuCommerceItem", "sku20002", null, "prod20002", null, 1, null, null, new ItemPriceInfo()); getCommerceItemManager().addSubItemToConfigurableItem(configurableItem, subskuItem); getCommerceItemManager().addItemToOrder(order, configurableItem);
Creating a Shipping Group
A ShippingGroup
contains information on the shipping address and delivery method for a group of commerce items. By default, a new Order
has one default ShippingGroup
. As items are added to the Order
, these items automatically become part of the default ShippingGroup
. Once a second ShippingGroup
is added to the Order
, all the items in the Order
are removed from the default ShippingGroup
and must be explicitly added to one of two shipping groups. Relationships must now be created to associate the items with shipping groups. (For more information, see Assigning Items to Shipping Groups.)
Follow these steps to create a new ShippingGroup
and add it to an Order
:
Call
ShippingGroupManager.createShippingGroup()
.Make any changes to the
ShippingGroup,
such as setting the address.Call
ShippingGroupManager.addShippingGroupToOrder(pOrder, pShippingGroup)
to add theShippingGroup
to theOrder
.
Refer to the following example:
// Get a reference to the OrderManager OrderManager orderManager = (OrderManager) request.resolveName("/atg/commerce/order/OrderManager"); // Create the ShippingGroup ShippingGroup shippingGroup = shippingGroupManager.createShippingGroup(); // Add the ShippingGroup to the Order shippingGroup.addShippingGroupToOrder(pOrder, shippingGroup);
When setting the shipping and billing addresses, normally you pass a RepositoryContactInfo
object to setShippingAddress()
or setBillingAddress()
. If you want to use a ContactInfo
object instead, but do not want to subclass RepositoryContactInfo
(see defaultShippingGroupAddressType in the OrderTools section), you must modify some Nucleus components. List the properties of your address object in the savedProperties
property of /atg/commerce/order/processor/SaveShippingGroupObjects
and the loadProperties
property of atg/commerce/order/processor/LoadShippingGroupObjects
.
Creating Multiple Shipping Groups
Multiple shipping groups (which implement Multishipment
) on a commerce site permit a customer to ship parts of an order to different addresses using different methods of delivery.
For example, suppose a customer enters the checkout process on a site that supports multiple shipping methods for a single order. The customer chooses to have the items shipped to different locations. The site must provide a UI that allows the customer to enter an address, and then associate it with a shipper, such as UPS or US Postal.
After the customer selects a shipper, a ShippingGroup
is created. The site must then provide a UI that allows the customer to associate items with that shipping group. If there is only one shipping group, then all the items to be shipped will go into that shipping group. If more than one shipping group is associated with the order, then the customer must decide which items go into each group.
Creating a Payment Group
A PaymentGroup
contains information about the payment method that will be used to purchase a group of commerce items. By default, a new Order
has one default PaymentGroup
. As items are added to the Order
, these items automatically become part of the default PaymentGroup
. Once a second PaymentGroup
is added to the Order
, all the items in the Order
are removed from the default PaymentGroup
and must be explicitly added to one of the two payment groups. Relationships must now be created to associate the items with payment groups. (For more information, see the Assigning Costs to Payment Groups section.)
Payment groups also contain a requisitionNumber
property for orders that require approval before a means of payment can be specified. Orders with requisition numbers are automatically assumed to require approval. (See the Managing the Order Approval Process chapter for information on approvals.)
Follow these steps to create a new PaymentGroup
and add it to an Order
:
Call
PaymentGroupManager.createPaymentGroup()
.Make any changes to the
PaymentGroup
. For example, you could set the credit card number and expiration date.Call
PaymentGroupManager.addPaymentGroupToOrder(pOrder, pPaymentGroup)
to add the payment group to the order.
Refer to the following example:
// Get a reference to the OrderManager OrderManager orderManager = (OrderManager) request.resolveName("/atg/commerce/order/OrderManager"); // Create the PaymentGroup PaymentGroup paymentGroup = paymentGroupManager.createPaymentGroup(); // Add the PaymentGroup to the Order paymentGroupManager.addPaymentGroupToOrder(pOrder, paymentGroup);
Creating Multiple Payment Groups
Multiple payment groups follow a similar pattern to multiple shipping groups. The payment groups implement Multipayment
, and permit a customer to split the cost of an order by amount or by items. For example, the customer might put the first $1000 of a $1250 order on a Visa credit card, then pay the the remaining $250 using points earned on the site during previous visits.
While customers can select payment methods by item level, amount level, or any combination of the two, you can limit the ways in which an order’s costs can be split, if necessary.