Choose an appropriate template mechanism

In general, the format of any template should follow the same structure as the standard template.

Keeping this general rule in mind, there are two ways to customize the standard template, differentiated by the amount of data they return and how they can be called:
  • Static templates
  • Dynamic templates

Static templates provide the ability to add new elements but not remove any of the defaults. A static template is pervasive, as it is picked up by default by an API whenever that API is invoked.

Dynamic templates provide the ability to add new elements and remove any of the default elements from the standard template. A dynamic template is an instance, as it is picked up only for a specific API call, such as when configured to do so during user interface extensibility.

A comparison of the differences between the two types of template mechanisms is summarized in the following table.

Template Types Allowed XML Elements Behavior
Static Template

Default template elements cannot be removed.

New elements can be added.

Pervasive. Picked up by default by an API.
Dynamic Template

Default template elements can be removed.

New elements can be added.

 Instance. Picked for a specific API call, as configured during user interface extensibility.

Choose which of these mechanisms best fits your business needs and adhere to it.

Remember that when you define a dynamic template, all possible values are returned. In order to return the smallest amount of data for an element, when you are pruning away elements you don't need, you need to include its parent with at least one of its attributes.

If you leave an element blank or include unwanted attributes in the parent element all values are returned, as illustrated in the following example of a poorly pruned dynamic template.

A poorly pruned dynamic template

<!-- getOrderDetails Output XML --> 
<Order> 
   <OrderLines> 
     <!--1 or more order line--> 
       <OrderLine> 
          <Item CountryOfOrigin="" ItemDesc="" ItemID=""/> 
          <Schedules> 
             <Schedule Attr1 ...... /> 
          </Schedules> 
       </OrderLine> 
   </OrderLines> 
<Order>

Since the poorly pruned dynamic template specifies all OrderLine attributes as well as a few Item and Schedule attributes, the API returns values similar to the following.

<OrderLine AllocationDate="03/28/2002" CarrierAccountNo="112233" 
CarrierServiceCode="Next Day Air" Createprogid="CustomTester"
Createts="03/28/2002" Createuserid="CustomTester" CustomerLinePONo="999"
CustomerPONo="111" DeliveryCode="AIR" DepartmentCode="Clothing"
ExtendedFlag="" ExternalReference1="" ExternalReference2="" 
ExternalReference3="" ExternalReference4="" ExternalReference5="" 
FreightTerms="Buyer" HoldFlag="N" HoldReasonCode="HoldReas" 
ImportLicenseExpDate="08/08/2002" ImportLicenseNo="225588" 
InternalReference1="" InternalReference2="" InternalReference3="" 
InternalReference4="" InternalReference5="" KitCode=""
LineClass="" LineSeqNo="1.1" LineType="Single" Lockid="1" MarkForKey=""
Modifyprogid="CustomTester" Modifyts="03/28/2002" 
Modifyuserid="CustomTester" OrderClass="NEW" 
OrderHeaderKey="200203281036245174" OrderLineKey="200203281036245175"
OrderedQty="5.00" OrigOrderLineKey="" OriginalOrderedQty="5.00"
OtherCharges="0.00" OtherChargesPerLine="0.00" OtherChargesPerUnit="0.00"
PackListType="Bill" PersonalizeCode="PersCode" PersonalizeFlag="" 
PickableFlag="Y" PricingDate="01/01/2500" PrimeLineNo="1" 
Purpose="Purpose" ReceivingNode="B1N1" ReqCancelDate="01/01/2500" 
ReqDeliveryDate="04/04/2002" ReqShipDate="03/30/2002"
ReservationID="" ReservationPool="" SCAC="UPS" ShipNode="E1N1" ShipToID=""
ShipToKey="" ShipTogetherNo="Y" SplitQty="0.00" SubLineNo="1" 
TotalDiscountAmount="0.00" TotalOtherCharges="0.00"> 
<Item CountryOfOrigin="" ItemDesc="" ItemID=""/> 
<Schedules> 
<Schedule ExpectedDeliveryDate="" ExpectedShipmentDate=""
TagNumber="" OrderHeaderKey="" OrderLineKey="" OrderLineScheduleKey=""
ScheduleNo="" ShipByDate="" Quantity=""  PromisedApptStartDate=""
PromisedApptEndDate=""/> 
</Schedules> 
</OrderLine> 
</OrderLines> 
</Order>

A carefully pruned custom output template

In this carefully pruned custom output template, the dynamic template has been trimmed down, keeping in mind the following guidelines:
  • The structure of the custom output template mirrors the structure of the standard output template.
  • Excess elements (regarding kits, schedules, addresses, and so forth) are pruned away.
  • Parent elements are populated with one attribute in order to suppress excess detail. For example, specifying the OrderNo attribute for the Order element suppresses all of the other Order attributes. 
<!-- getOrderDetails Output XML --> 
<Order OrderNo=””> 
   <OrderLines>
		    <!--1 or more order line--> 
        <OrderLine PrimeLineNo=""> 
            <Item CountryOfOrigin="" ItemDesc="" ItemID=""/> 
     </OrderLine> 
    </OrderLines> 
</Order>

Since this carefully pruned custom output template specifies only a few Item attributes and only one attribute for its parent element, the getOrderDetails() API returns only the following values:

<?xml version="1.0" encoding="UTF-8" ?> 
<Order OrderNo=Y00000765> 
   <OrderLines> 
      <OrderLine PrimeLineNo="1"> 
          <Item CountryOfOrigin="IN" Item Description" 
ItemDesc="Green Sari" ItemID="GNSARI5LT" /> 
       </OrderLine> 
       <OrderLine PrimeLineNo="3"> 
          <Item CountryOfOrigin="CA" ItemDesc="Pink Scarf" 
ItemID="PKSCARF4LT" /> 
       </OrderLine> 
    </OrderLines> 
</Order>

This method of pruning the templates improves the performance as database access to order schedules and other unwanted elements has been prevented.