ATG Commerce Programming Guide

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:

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:

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

Auxiliary data is a construct that exists in a CommerceItem object. This structure allows arbitrary data to be stored with a CommerceItem. This data could be the options for a CommerceItem such as size and color. It could also refer to the product reference in the catalog. An important concept is that any data that is inserted into the auxiliary data can be serialized at any time in a system that contains remote components. When defining AuxiliaryData objects, the classes must be defined as serializable. As initially defined, the class includes ProductID, ProductRef, PropertyValue, and CatalogRef properties.

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 Standard Catalog chapter of this manual.

Follow these steps to create a new ConfigurableCommerceItem and associate it with an Order:

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:

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 saveProperties 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. The following assumptions were made regarding Multishipment:

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 which group.

Creating a Payment Group

A PaymentGroup contain 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 more information on approvals.)

Follow these steps to create a new PaymentGroup and add it to an 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 (which implement Multipayment) on a commerce site permit a customer to split the cost of an order by amount and/or items. For example, suppose a customer begins the checkout process on a site that supports multiple payment methods for a single order. The customer chooses to partition payment by putting the first $1000 of a $1250 order on a Visa credit card. The customer then chooses to pay for the remaining $250 using points earned on the site during previous visits.

The following assumptions were made regarding Multipayment:

The base commerce classes have built-in support for multiple payment methods. Multipayment allows customers to pay for purchases using multiple payment methods. For example, a customer can choose to pay for an order using two or more credit cards and a gift certificate. 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. The product UI for this component is entirely JSP-based.