Develop > Presentation layer > Customize promotions > Promotion engine customization

Promotion DTD example

The Promotions tool is not shipped with a DTD for the runtime promotion XML; however, this model DTD provides a perspective of what a promotion definition might look like.

<?xml version="1.0" encoding="UTF-8"?>   
<!-- Promotion is the root element -->   
<!ELEMENT Promotion
       (PromotionKey,        PromotionGroupKey,        TypedNLDescription,        Priority,        Exclusive,        ExemptPolicyList,        ExplicitlyAppliedPolicyList,        Status,        LastUpdate,        LastUpdateBy,        PerOrderLimit,        PerShopperLimit,        ApplicationLimit,        Schedule,        PromotionType,        PromotionCodeCue,        PromotionCodeRequired,        SkipTargetingConditionOnProperPromotionCodeEntered,        CheckTargetingConditionAtRuntime,        PromotionCodeCondition,        Targeting,        CustomConditions,        PurchaseCondition)
   >    


<!-- The impl attribute declares the class name that implements the 
    promotion object.  Current the only implementation is: 
    "com.ibm.commerce.marketing.promotion.DefaultPromotion" All promotion
    implementations must implement interface
    "com.ibm.commerce.marketing.promotion.Promotion"
     --> 
<!ATTLIST Promotion impl CDATA #IMPLIED > 
<!-- This is the definition of the key of a promotion, promotions are scoped 
    by store and has a unique name.  Each promotion has a number of versions 
    and revisions.  Based on the design, in the database storekey, promotion 
    name, version and revision together make up the unique key of a promotion.
     -->
<!ELEMENT PromotionKey (PromotionName,StoreKey,Version,Revision) > 
<!-- Name of the promotion, which is also used as the code in CALCODE table 
    in Commerce 
     -->    
<!ELEMENT PromotionName (#PCDATA) >
<!ELEMENT StoreKey (DN,Identifier) >
<!ELEMENT DN (#PCDATA) >
<!ELEMENT Identifier (#PCDATA) > 
<!ELEMENT v(#PCDATA) >
<!ELEMENT Revision (#PCDATA) > 
<!-- Each promotion belongs to a single promotion group. The group is 
    identified by the PromotionGroupKey which is made up of a group name and a 
    store key. Groups are scoped by store 
     -->     

<!ELEMENT PromotionGroupKey (GroupName,StoreKey) >
<!ELEMENT GroupName (#PCDATA) > 
<!-- Each promotion can have multiple descriptions associated with it each 
    description can have a type and a locale associated with it. There is a 
    default locale defined for each promotion. The implemenation of 
    TypedNLDescription is declared in the impl attribute of this element. 
    Currently the only implementation is:         "com.ibm.commerce.marketing.promotion.TypedNLDescription"
    All implementations should implement interface
        "com.ibm.commerce.marketing.promotion.Description"
     -->    

<!ELEMENT TypedNLDescription (DefaultLocale,Description+) >
<!ATTLIST TypedNLDescription impl CDATA #IMPLIED > 
<!-- Locale string such as: en_US, fr_FR -->
<!ELEMENT DefaultLocale (#PCDATA) >
<!ELEMENT Description (#PCDATA) > 
<!-- Locale string such as: en_US, fr_FR --> 
<!ATTLIST Description locale CDATA #IMPLIED > 
<!-- Possible values are: "admin", "short", "long" and "custom1" through 
    "custom5" 
     -->
<!ATTLIST Description type CDATA #IMPLIED > 
<!-- Priority of the promotion, arbitrary integer, the bigger the number is 
    the higher the priority.  
     -->
<!ELEMENT Priority (#PCDATA) > 
<!-- The exclusivity of a promotion.  Possible values are:      0: Not exclusive
     1: Exclusive at group level
     2: Exclusive at global level
     3: A compatible mode, order level promotions with this exclusivity cannot
        be combined with any product level promotions.
     -->        
<!ELEMENT Exclusive (#PCDATA) > 
<!-- The following two elements are currently empty, they are for future 
    enhancement purposes
     -->    
<!ELEMENT ExemptPolicyList ANY >
<!ELEMENT ExplicitlyAppliedPolicyList ANY > 
<!-- Status of the current promotion, possible values are:     0: Inactive
    1: Active
    2: Deleted
    3: Suspended
    4: Obsolete
     -->
<!ELEMENT Status (#PCDATA) > 
<!-- Timestamp of last update -->
<!ELEMENT LastUpdate (#PCDATA) > 
<!-- The person who last updated the promotion -->
<!ELEMENT LastUpdateBy (CustomerKey) > 
<!-- Key to any user -->
<!ELEMENT CustomerKey (LogonId) > 
<!-- Logon ID of a user -->
<!ELEMENT LogonId (#PCDATA) > 
<!-- Limit on how many times this promotion can be applied to a single 
    order: 
    -1:   unlimited
    0-infinite:  actual number of times allowd
     -->      
<!ELEMENT PerOrderLimit (#PCDATA) > 
<!-- Limit on how many times this promotion can be applied to a single 
     customer in his or her lifetime. Effective only on registered customers. 
    -1:         unlimited
    0-infinite: actual number of times allowd
     -->      
<!ELEMENT PerShopperLimit (#PCDATA) > 
<!-- Limit on overall how many times this promotion applied, 
    -1:          unlimited
    0- infinite: actual number of times allowd
     -->      
<!ELEMENT ApplicationLimit (#PCDATA) > 
<!-- Schedule within which this promotion is active -->
<!ELEMENT Schedule (DateRange,TimeWithinADay,Week) > 
<!-- The implemenation of the schedule object, currently the only 
    implementation is:       "com.ibm.commerce.marketing.promotion.schedule.PromotionSchedule"
    and all implementations must implement"
      "com.ibm.commerce.marketing.promotion.schedule.Schedule"
     -->    
<!ATTLIST Schedule impl CDATA #IMPLIED >
<!ELEMENT DateRange (Start,End) > 
<!-- Currently the only valid value is: 
      "com.ibm.commerce.marketing.promotion.schedule.DateRangeSchedule"
     -->
<!ATTLIST DateRange impl CDATA #IMPLIED > 
<!-- This element is used in both DateRange and TimeWithinADay. When used in 
    DateRange, value should follow format DD-MM-YYYY; when used in TimeWithinADay,     value should follow format HH:MM:SS. 
    -->
<!ELEMENT Start (#PCDATA) > 
<!-- Is the starting point included -->
<!ATTLIST Start inclusive CDATA #IMPLIED > 
<!-- This element is used in both DateRange and TimeWithinADay. When used in 
    DateRange, value should follow format DD-MM-YYYY; when used in 
    TimeWithinADay, value should follow format HH:MM:SS. 
     -->
<!ELEMENT End (#PCDATA) > 
<!-- Is the end point included -->
<!ATTLIST End inclusive CDATA #IMPLIED >
<!ELEMENT TimeWithinADay (Start,End) > 
<!-- Currently, the only valid value is: 
    "com.ibm.commerce.marketing.promotion.schedule.TimeRangeWithinADaySchedule" 
     -->
<!ATTLIST TimeWithinADay impl CDATA #IMPLIED > 
<!-- Weekdays on which this promotion is active. -->
<!ELEMENT Week (WeekDay+) > 
<!-- Currently, the only valid value is: 
    "com.ibm.commerce.marketing.promotion.schedule.WeekDaySchedule"
     --> 
<!ATTLIST Week impl CDATA #IMPLIED > 
<!-- Possible values are: 
    Sunday
    Monday
    Tuesday
    Wednesday
    Thursday
    Friday
    Saturday
    -->
<!ELEMENT WeekDay (#PCDATA) > 
<!-- The type of promotion, possible values are:     0: Promotions targeted customer segments.
    1: Promotions targeted individual customers, that is, coupon promotions.
     -->    

<!ELEMENT PromotionType (#PCDATA) > 
<!-- String value of hints on the promotion code, can be empty. The default 
    function uses this column to store the required promotion code for this 
    promotion.  This column may not be used if a custom promotion code 
    application is used 
     -->
<!ELEMENT PromotionCodeCue (#PCDATA) > 
<!-- Whether a correct promotion code is needed in order to redeem 
    this promotion.  
    true: yes, 
    false: no 
     -->
<!ELEMENT PromotionCodeRequired (#PCDATA) > 
<!-- Whether targeting condition should be check at all at runtime
    true: yes, targeting condition needs to be checked
    false: no, targeting condition can be skipped. 
     -->
<!ELEMENT CheckTargetingConditionAtRuntime (#PCDATA) > 
<!-- Whether the targeting condition should be ignored when a correct 
    promotion code has been entered: 
    true:  ignore 
    false: do not ignore
    This flag will only be effective when CheckTargetingConditionAtRuntime is 
    set to true. Otherwise, targeting condition won't be checked at all, 
    regardless of whether a promotion code has been entered or not.
     -->
<!ELEMENT SkipTargetingConditionOnProperPromotionCodeEntered (#PCDATA) > 
<!-- The implemenation of the promotion code condition, must be customized 
    if a custom promotion code application is used. Currently empty. -->
<!ELEMENT PromotionCodeCondition ANY > 
<!-- The implemenation class of PromotionCodeCondition. Currently, the only 
    valid value is:        "com.ibm.commerce.marketing.promotion.condition.PromotionCodeCondition"
    All custom implemenations must implement
       "com.ibm.commerce.marketing.promotion.condition.Condition"
     --> 
<!ATTLIST PromotionCodeCondition impl CDATA #IMPLIED > 
<!-- Targeting condition of this promotion -->
<!ELEMENT Targeting (TargetedProfile, ExcludedProfile?) > 
<!-- Implementation of targeting condition, currently, the only valid value 
    is:       "com.ibm.commerce.marketing.promotion.condition.TargetingCondition"
     -->
<!ATTLIST Targeting impl CDATA #IMPLIED > 
<!-- Targeted customer profiles -->
<!ELEMENT TargetedProfile (CustomerProfileKey) * > 
<!-- Excluded customer profiles --> 
<!ELEMENT ExcludedProfile (CustomerProfileKey) * > 
<!-- Key to a customer profile -->
<!ELEMENT CustomerProfileKey  (OwnerDN, ProfileName) > 
<!-- DN of member or organization that owns this customer profile -->
<!ELEMENT OwnerDN (#PCDATA) > 
<!-- Name of the customer profile -->
<!ELEMENT ProfileName (#PCDATA) > 
<!-- The list of custom conditions -->
<!ELEMENT CustomConditions (Condition)* > 
<!-- Custom condition-->
<!ELEMENT Condition  ANY > 
<!-- Implementation class of the custom condition. All implementation must 
    implement interface
      "com.ibm.commerce.marketing.promotion.condition.Condition" 
     -->    
<!ATTLIST Condition impl CDATA #IMPLIED > 

<!-- This is the heart of a promotion, it defines the purchases a shopper 
    has to make in order to qualify for a promotion.  Current implementation is 
    a pattern based qualification, any other implementation is possible and 
    will require customization 
     -->
<!ELEMENT PurchaseCondition (Pattern,Distribution) > 
<!-- Implementation of PurchaseCondition, currently the only valid value for 
    this attribute:       "com.ibm.commerce.marketing.promotion.condition.PurchaseCondition"
    All custom implementations must implement the following interface:       "com.ibm.commerce.marketing.promotion.condition.Condition" 
     -->
<!ATTLIST PurchaseCondition impl CDATA #IMPLIED > 
<!-- Definition of the pattern, a pattern is made up of multiple constraints 
     -->
<!ELEMENT Pattern (Constraint)+ > 
<!-- The only valid value without customization is: 
    "com.ibm.commerce.marketing.promotion.condition.Pattern"
     -->
<!ATTLIST Pattern impl CDATA #IMPLIED > 
<!-- Definition of a constraint -->
<!ELEMENT Constraint (WeightedRange,FilterChain+) > 
<!-- Currently, the only valid value without customization is:     "com.ibm.commerce.marketing.promotion.condition.Constraint"
     -->
<!ATTLIST Constraint impl CDATA #IMPLIED > 
<!-- Definition of a weighted range in pattern based purchase condition -->
<!ELEMENT WeightedRange (LowerBound,UpperBound,Weight) > 
<!-- Without customization, the only valid value is: 
    "com.ibm.commerce.marketing.promotion.condition.WeightedRange"
     -->
<!ATTLIST WeightedRange impl CDATA #IMPLIED > 
<!-- Lower boundary of the quantity of order items that will satifisfy a 
    constraint, any positive integer. 
     -->
<!ELEMENT LowerBound (#PCDATA) > 
<!-- Upper boundary of the quantity of order items that will satifisfy a 
    constraint, any positive integer, >= LowerBound 
     -->
<!ELEMENT UpperBound (#PCDATA) > 
<!-- Please refer to the definiton of Weighted Range in the design document 
    usually possible values are: 0 and 1. 0: indicates lower boundary is used 
    to match patterns, 1 indicates the upper boundary is used to match patterns 
     -->
<!ELEMENT Weight (#PCDATA) > 
<!-- A chain of filters connected using "AND" -->
<!ELEMENT FilterChain (Filter)+ > 
<!-- Individual Filter definition, the body of this element is complete 
    dependent on the implementation of actual filters 
     -->
<!ELEMENT Filter ANY > 
<!-- This declares the implementation class of the filter. A fully 
    qualified class name is used. All implementation classes must implement 
    the following interface:       "com.ibm.commerce.marketing.promotion.condition.Filter"
     -->
<!ATTLIST Filter impl CDATA #IMPLIED > 
<!-- Definition of a distribution -->
<!ELEMENT Distribution (Type,Base,Currency?,PatternFilter, Range+) > 
<!-- Without customization, the only valid value for this attribute is:     "com.ibm.commerce.marketing.promotion.reward.Distribution"
     -->
<!ATTLIST Distribution impl CDATA #IMPLIED > 
<!-- Type of distribution, possible values are: "Volume" and "Tiered" -->
<!ELEMENT Type (#PCDATA) > 
<!-- The distribution is based on either "Cost" or "Quantity"  Note that 4
    combinations can be derived from "Type" and "Base" values. Only 3 of the 4 
    combinations are currently supported. The combination of "Tiered" and 
    "Cost" is currently not supported. 
     -->
<!ELEMENT Base (#PCDATA) > 
<!-- If the distribution is based on cost, this is the currency in which the 
    cost is expressed.
     -->
<!ELEMENT Currency (#PCDATA) > 
<!-- Specifies a filter that can be used to eliminate certain matched 
    patterns from participating in the distribution, body of this element is 
    completely dependent on individual filter implementation 
     -->
<!ELEMENT PatternFilter ANY > 
<!-- The implementation class for Pattern filters. All implementations must 
    implement the following interface:       "com.ibm.commerce.marketing.promotion.condition.PatternFilter"
    The default value should be:       "com.ibm.commerce.marketing.promotion.condition.DummyPatternFilter"
     -->    
<!ATTLIST PatternFilter impl CDATA #IMPLIED > 
<!-- Ranges in the distribution -->
<!ELEMENT Range (UpperBound, UpperBoundIncluded, LowerBound, 
    LowerBoundIncluded, RewardChoice) > 
<!-- Whether the upper bound is included in the distribution or not, "true" 
    or "false" -->
<!ELEMENT UpperBoundIncluded (#PCDATA) > 
<!-- Whether the lower bound is included in the distribution or not, "true" 
    or "false" -->
<!ELEMENT LowerBoundIncluded (#PCDATA) > 
<!-- Without customization, the only valid value is:     "com.ibm.commerce.marketing.promotion.reward.DistributionRange"
     -->
<!ATTLIST Range impl CDATA #IMPLIED > 
<!-- Each reward choice is made up of multiple rewards. Due to system 
    implementation limitation, currently only one reward is allowed -->
<!ELEMENT RewardChoice (Reward)+ > 
<!-- Each reward is made up of multiple Adjustment functions -->
<!ELEMENT Reward (AdjustmentFunction)+ > 
<!-- Without customization, the only valid value for this attribute is:     "com.ibm.commerce.marketing.promotion.reward.DefaultReward"
     -->
<!ATTLIST Reward impl CDATA #IMPLIED > 
<!-- Each adjustment function is made up of a FilterChain and an Adjustment.
    The filter chain narrows a matched pattern to a list of order items to 
    which the  the Adjustment is applied.
     -->
<!ELEMENT AdjustmentFunction (FilterChain,Adjustment) > 
<!-- Without customization, the only valid value for this attribute is:     "com.ibm.commerce.marketing.promotion.reward.AdjustmentFunction"
     -->
<!ATTLIST AdjustmentFunction impl CDATA #IMPLIED > 
<!--Adjustment element defines actually changes to be made to order items. 
    The body of this element is completely dependent on the implementation of 
    the individual Adjustment. The impl attribute of this element specifies 
    the implementation. All implementations must implement the following 
    interface: 
      "com.ibm.commerce.marketing.promotion.reward.Adjustment"
     -->
<!ELEMENT Adjustment ANY >
<!ATTLIST Adjustment impl CDATA #IMPLIED >

Related concepts

Customize promotions

+

Search Tips   |   Advanced Search