Creating Commerce Items, Shipping Groups, and Payment Groups

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 createObjectType() 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:

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:

  1. Call CommerceItemManager.createCommerceItem().

  2. Make any changes to the CommerceItem, such as setting the quantity.

  3. Call CommerceItemManager.addItemToOrder(pOrder, pCommerceItem) to add the CommerceItem 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 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:

  1. 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 a pSiteId parameter. If the siteId is null but multisite is in use, the method retrieves the ID from SiteContextManager.getCurrentSiteId.

  2. Make any changes to the CommerceItem, such as setting the quantity.

  3. Call CommerceItemManager.addItemToOrder(pOrder, pCommerceItem) to add the CommerceItem to the Order.

    In a multisite setting, the addItemToOrder() method and the related addAsSeparateItemToOrder() method use the validateSiteCompatibility() method to ensure that the item can be added to the order. If the item’s siteId is not null, that siteId is added to the order’s siteId. If the order’s creationSiteId is null, the item’s siteId 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:

  1. Call CommerceItemManager.createCommerceItem() to create the base commerce item.

  2. Call CommerceItemManager.addSubItemToConfigurableItem() or addAsSeparateSubItemToConfigurableItem() 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:

  1. Call ShippingGroupManager.createShippingGroup().

  2. Make any changes to the ShippingGroup, such as setting the address.

  3. Call ShippingGroupManager.addShippingGroupToOrder(pOrder, pShippingGroup) to add the ShippingGroup 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 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:

  1. Call PaymentGroupManager.createPaymentGroup().

  2. Make any changes to the PaymentGroup. For example, you could set the credit card number and expiration date.

  3. 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.