Handling instructions can be added to either shipping groups or individual commerce items. This section provides an example of how to create handling instructions for gift wrapping one item in a shipping group. The example also uses a repository with a wrapping paper item descriptor.

For additional, detailed examples of how to extend the purchase process to support new commerce objects, see the Extending the Purchase Process section in this guide. For information on how to create new item descriptors in a repository, see the SQL Repository Data Models chapter in the ATG Repository Guide. For more information on HandlingInstruction, see the ATG Platform API Reference.

Step 1: Create a GiftwrapHandlingInstruction class that extends the atg.commerce.order.HandlingInstructionImpl class. Add a property to identify the wrapping paper. For example:

public String getWrappingPaperId();
public void setWrappingPaperId(String pWrappingPaperId);

Step 2: Add support for this class to the OrderTools component. For example, in the localconfig directory add the following lines to /atg/commerce/order/OrderTools.properties:

handlingTypeClassMap+=giftwrapHandlingInstruction=
mypackage.GiftwrapHandlingInstruction
beanNameToItemDescriptorMap+=mypackage.GiftwrapHandlingInstruction=
giftwrapHandlingInstruction

Step 3: Add support for the new item descriptor to orderrepository.xml. The orderrepository.xml file is located in /atg/commerce/order/orderrepository.xml in the configpath.

First, add the new type to the handlingInstruction item descriptor:

<table name="dcspp_hand_inst" type="primary"
       id-column-name="handling_inst_id">
  <property name="type" data-type="enumerated"
            default="handlingInstruction" expert="true"
            display-name="Type">
    <attribute name="useCodeForValue" value="false"/>
      <option value="handlingInstruction" code="0"/>
      <option value="giftlistHandlingInstruction" code="1"/>
  </property>
     . . .
</table>

Second, add the new item descriptor:

<item-descriptor
      name="giftwrapHandlingInstruction"
      super-type="handlingInstruction"
      sub-type-value="giftwrapHandlingInstruction"
      cache-mode="locked"
      display-name="Gift wrap Handling Instruction">
  <attribute name="writeLocksOnly" value="true"/>
  <table name="dcspp_wrap_inst"
         id-column-name="handling_inst_id">
    <property name="wrappingPaperId"
              column-name="wrap_id"
              data-type="string"
              display-name="Wrapping Paper Id"/>
  </table>
</item-descriptor>

Step 4: Create a method that adds the handling instruction to the order in a class that extends the HandlingInstructionManager:

public wrapCommerceItemInShippingGroup(ShippingGroup
  pGiftShippingGroup, CommerceItem pWrappedItem,String pWrappingPaperId)
  {
     GiftwrapHandlingInstruction giftwrap = (GiftwrapHandlingInstruction)
     handlingInstructionManager.createHandlingInstruction(
     "giftwrapHandlingInstruction",
     pGiftShippingGroup.getId(), pWrappedItem.getId(),
                                 pWrappedItem.getQuantity());
     giftwrap.setWrappingPaperId(wrappingId);
     pGiftShippingGroup.addHandlingInstruction(giftwrap);
  }

Step 5: Add any additional processors. For example, you could add a processor to the validateForCheckout pipeline to validate the wrapping paper type.