The properties of a promotion RepositoryItem
are documented in the table below. These properties work together to form a description of what discount to give, under which conditions it should be given, and the mechanism by which the discount is applied.
In addition to the standard property types (strings, numbers, dates, etc.) promotions also include a property type unique to promotions items, pmdlRule
, which stores the PMDL rule for the promotion as a string. This property has a custom property editor associated with it in the Promotions section of the ATG Control Center; see the ATG Commerce Guide to Setting Up a Store for information.
The following table describes the pricing model properties available in the Item, Shipping, Tax, and Order descriptors when you create a commerce item. These descriptors are defined in /atg/commerce/pricing/pricingModels.xml
, which is located in <ATG10dir>/DCS/config/config.jar
.
Property Name | Type | Values | Descriptions |
---|---|---|---|
| double | any double | Number by which the item is discounted. Works in conjunction with Note: This property is no longer used, and is maintained only for backward compatibility. |
| boolean |
| Determines whether the promotion can be given to a customer only once. If set to Note: This property is ignored if the |
| time stamp | any date | The date that the promotion stops being effective. Used when the Together with the |
| date | any date | Read-only. The date when the promotion was created. |
| string | any string | Provides a short description of the item. |
| string |
| Read-only. The type of discount this promotion gives. Note: This property is no longer used, and is maintained only for backward compatibility. |
| string | any string | Specifies the name visible in the user interface. |
| boolean |
| Specify Note: As a general rule, you should never delete promotions and instead disable them by setting the |
| date | any date | The date that the promotion stops being delivered to people, if the collection filtering feature is implemented to use this property. |
| time stamp | any date | The date that the promotion stops being effective. Used when the Together with the |
| boolean |
| If both this property and the Note: This property is ignored if the |
| boolean |
| Setting the -- Setting the |
| map | map of object to object | The media, such as icons, associated with this discount. |
| boolean |
| A property used for shipping promotions only. It determines whether a shipping promotion can discount a single order multiple times. If set to |
| string | any valid PMDL rule | This is the PMDL rule describing the conditions under which this promotion should take effect. The rule is created in the ATG Control Center using the interface designed for promotion creation. For more information, see the ATG Commerce Guide to Setting Up a Store. |
| enum | calculator | The calculator that computes and applies this promotion’s discount. Note: This property is no longer used, and is maintained only for backward compatibility. |
| integer | any integer | The priority of the promotion. Promotions are applied in order of priority, with low priority numbers applied first. Engines sort the promotions by the value of this property. Note that this property functions within the context of a particular promotion type. For example, you can specify how a given Item Discount promotion is applied compared to other Item Discount promotions, but not the order in which Item Discounts are applied compared to Shipping Discounts. |
| boolean |
| Determines whether the usage period for the promotion is fixed or relative. If |
| date | any date | The date that the promotion begins to be able to be delivered to people, if the collection filtering feature is implemented to use this property. |
| int | any int | Determines the usage period in minutes for the promotion. Used when the The promotion becomes active as soon as the user receives the promotion; that is, the promotion is added to the list of promotions in the user’s Note: This property is ignored when the |
| enum | Version 10 and later: Item Discount | Ready-only. The type of discount this promotion gives. This is set during item creation. Note: For versions prior to Oracle ATG Web Commerce 10, values are: Item Discount– Percent Off |
| int | any positive integer, zero | The number of orders for a given customer to which the promotion can be applied. If this number hits zero, the promotion can no longer be applied. Note: A promotion can sometimes discount a single order multiple times. This is still considered one “use.” For shipping promotions only, you can prevent the promotion from discounting a single order multiple times by setting the Note: This property is ignored when the |
| long | any long | Hidden. Used by the SQL Repository to protect against data corruption caused by two different threads attempting to modify the same item the same time. |
| promotionFolder | any promotion | The parent folder of the promotion. |
| set | set of Site | The |
| set | set of siteGroup items | The |
| string | any template name string | The |
| map | map of template place holder values | Placeholder values are used to build the PMDL from a template; see Adding New Promotions Templates. |
| int | 0 or 1 | The value in this field identifies whether or not the promotion is read-only (0) or writeable (1). |
| int | 1 or 2 | The value in this field identifies whether the PMDL is pre-Oracle ATG Web Commerce 10 (version 1), or Oracle ATG Web Commerce 10 or later (version 2). |
One important part of promotion creation is making sure that the promotion can only be used in the way you intend it to be used. Incorrectly worded or configured promotions could allow customers to receive greater benefits from the promotion than you intended. The following list describes issues to keep in mind when you are creating promotions:
Check the
startDate
,endDate
,beginUsable
, andendUsable
dates of all promotions to prevent a promotion from taking effect before you are ready for it.Note: When setting dates for a promotion, be aware that a number of factors can cause the promotion to be unusable for a number of minutes after it is set to be active and to be usable after it is set to expire, depending on the schedule set for the pricing engine (for global promotions) or the
PricingModelHolder
(for both global and non-global promotions).Because it can be resource intensive to collect a user’s list of promotions, or pricing models, the session-scoped
UserPricingModels
component (classatg.commerce.pricing.PricingModelHolder
) stores them in a session cache. When a session starts for a user,UserPricingModels
queries each pricing engine for the customer’s promotions.PricingModelHolder
is schedulable, and can also be configured to periodically update the promotions cache.These promotions include both the promotions in the user’s
activePromotions
profile property and the list of global promotions. To retrieve the list of global promotions, the pricing engine uses itsglobalPromotionsQuery
property to query the Promotions repository for all promotions where theglobal
property is set totrue
, and it does so everyx
minutes as defined by the schedule specified in itsupdateSchedule
property. Once collected, the pricing models inUserPricingModels
are then used for all pricing operations during the user’s session.Consequently, if a user’s session is created after you have added a new global promotion but before the next scheduled job to update the pricing engine’s list of global promotions, the user will not receive the new global promotion. You can prevent this situation by manually calling the
pricingEngine.loadGlobalPromotions
method when you add the new global promotion. Additionally, if a user’s session was created before you added a new promotion (either targeted or global), that user will never receive the new promotion. This is because the user’s list of pricing models has already been collected and stored in the user’sUserPricingModels
. To prevent this situation, manually call thepricingModelHolder.initalizePromotions
method when you add any new promotion (targeted or global). TheinitializePromotions
method generates a new list of pricing models to store in the user’sUserPricingModels
. (Note that thepricingModelHolder.initializePromotions
method should be called after thepricingEngine.loadGlobalPromotions
method in order to collect all new global promotions.)For more information on the
PricingModelHolder
class, see the PricingModelHolder section. For more information on the pricing engine APIs, see the Commerce Pricing Engines chapter.When creating promotions, evaluate the wording of the discount rule carefully to make sure that only the intended products receive the promotion. Be as specific as possible when creating rules. For example, if a particular brand is on sale, specify the brand in the rule rather than relying on an attribute of the brand that you might think is unique.
Use caution when creating “infinite use” promotions, which a customer can use an infinite number of times during a specified time period. Be certain the
beginUsable
andendUsable
dates are set correctly.