Using PMDL Rules

The promotions user interface consists of the standard repository editor. In the ATG Control Center, access the promotions interface by clicking the Promotions link under the Pricing topic. For more information, refer to the ATG Control Center online help and the Using the Discount Rule Editor to Create PMDL Rules section.

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.

These properties serve the following functions:

Mechanism of discount: discountCalculatorService
Under what conditions the promotion should be applied. This is defined in the pmdlRule property.
What promotion to give: all other properties, including amount, discountType, etc. Also includes the ItemDescriptor type.

Most of the property types should be familiar to anyone who has used an ATG platform repository editor before. These common types include strings, numbers, dates, and so on. The new property type unique to promotions is the pmdlRule property that stores the PMDL (Pricing Model Description Language) rule. This property has a custom property editor associated with it in the Promotions section of the ATG Control Center.

The PMDL rule editor functions exactly like any other ATG expression editor. The PMDL editor allows you to create a sentence out of the available building blocks. This sentence describes the circumstances under which a promotion will be delivered. The available building blocks are listed in pull-down menus in the ATG Control Center.

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 <ATG2007.3dir>/DCS/config/config.jar.

Property Name	Type	Values	Flags
`adjuster` (display name: Discount Price or Percentage, depending on the discount type)	double	any double	none
	Number by which the item is discounted. Works in conjunction with `discountType` to specify the discount to be applied. For example, an adjuster of 15 and a `discountType` of `percentOff` produce a discount of “15 percent off.”
`allowMultiple` (display name: Give to a customer more than once)	Boolean	`true` or `false`	none
	Determines whether the promotion is given to a customer only once. If set to `false`, the system delivers the promotion only once. If set to `true`, the system adds a copy of the promotion to the customer’s profile every time the customer performs an action that qualifies him or her to receive it. Consequently, a single order may be discounted by multiple copies of the promotion. Note: This property is ignored if the `global` property is set to `true`.
`beginUsable`	date	any date	none
(display name: Usage start date)	The date that the promotion becomes effective. Used when the `relativeExpiration` property is set to `false`. Note: This property is ignored if the `global` property is set to `true`.
`creationDate`	date	any date	read-only
(display name: Creation date)	The date when the promotion was created.
`description`	string	any string	none
(display name: Description)	Provides a short description of the item.
`discountType` (display name: Discount type)	string	`percentOff amountOff fixedPrice`	read-only
`discountType` (display name: Discount type)	The type of discount this promotion gives. This is set during item creation. (Note that two promotions can have different values for `type` and the same values for `discountType`. See the `type` property.)
`displayName`	string	any string	none
(display name: Name)	Specifies the name visible through user interface.
`enabled` (display name: Enabled)	Boolean	`true` or `false`	none
`enabled` (display name: Enabled)	Specify `true` to enable the promotion. If enabled, the promotion takes effect according to the specified distribution period. If disabled, the promotion never takes effect regardless of the distribution period. Note: As a general rule, you should never delete promotions and instead disable them by setting the `enabled` property to false. This approach eliminates the possibility of deleting a promotion that has been used in orders on your site, which produces errors.
`endDate`	date	any date	none
(display name: Distribute through)	The date that the promotion stops being delivered to people, if the collection filtering feature is implemented to use this property.
`endUsable`	date	any date	none
(display name: Usage end date)	The date that the promotion stops being effective. Used when the `relativeExpiration` property is set to `false`. Note: This property is ignored if the `global` property is set to `true`.
`giveToAnonymousProfiles`	Boolean	`true` or `false`	none
(display name: Give to anonymous customers)	If both this property and the `global` property are `false`, then only registered visitors who qualify receive the promotion. If this property is `true`, and the `global` property is `false`, then anonymous visitors and registered visitors who qualify receive the promotion. Note: This property is ignored if the `global` property is set to `true`.
`global`	Boolean	`true` or `false`	none
(display name: Automatically apply to all orders)	Setting the `global` property to `true` indicates that this promotion will be offered an unlimited number of times, to all visitors (including anonymous visitors), for use on an unlimited number of orders, during the specified distribution period – regardless of the values set for the following properties: -- `allowMultiple` -- `beginUsable` -- `endUsable` -- `giveToAnonymousProfiles` -- `relativeExpiration` -- `timeUntilExpire` -- `uses` Setting the `global` property to `false` indicates that the system delivers and applies the promotion according to all of the values specified for the promotion.
`media`	map	map of object to object	none
(display name: Media)	The media, such as icons, associated with this discount.
`oneUsePerOrder` (display name: One use per order)	Boolean	`true` or `false`	none
`oneUsePerOrder` (display name: One use per order)	A property used for shipping promotions only. It determines whether a shipping promotion can discount a single order multiple times. If set to `true`, then only one shipping group in the order can use the promotion. If set to `false`, then it is possible for each shipping group in the order to be discounted by the promotion.
`pmdlRule`	string	any valid PMDL rule	none
(display name: Discount rule)	This is the Pricing Model Description Language (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 Using the Discount Rule Editor to Create PMDL Rules section.
`pricingCalculatorService`	enumerated	for example, `/atg/commerce/pricing/ calculators/ ItemDiscountCalculator`	none
(display name: Pricing Calculator)	Specifies the calculator that computes and applies this promotion’s discount.
`priority`	integer	any integer	none
(display name: Order of application)	The priority of the promotion. Promotions are applied in order of priority, with low priority numbers applied first. Engines sort the value of this property.
`relativeExpiration` (display name: Usage Period)	Boolean	`true` or `false`	none
`relativeExpiration` (display name: Usage Period)	Determines whether the usage period for the promotion is fixed or relative. If `false`, the promotion’s usage period is determined by the dates set in the `beginUsable` and `endUsable` properties. If `true`, the promotion’s usage period is set according to the date it is received by the user (that is, when the promotion is added to the user’s `activePromotions` profile property). The start date and time is set when the user receives the promotion. The end date and time is set by the start date/time and the value of the `timeUntilExpire` property.
`startDate`	date	any date	none
(display name: Distribute starting)	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.
`timeUntilExpire` (display name: Redeemable for)	int	any int	none
`timeUntilExpire` (display name: Redeemable for)	Determines the usage period in minutes for the promotion. Used when the `relativeExpiration` property is set to `true`. When used, the start date and time of the promotion is set when the user receives the promotion; that is, the promotion is added to the list of promotions in the user’s `activePromotions` profile property. The end date and time is then determined by the start date/time and the number of minutes specified in this property. Note: This property is ignored when the `global` property is set to `true`.
`type` (hidden)	enumerated	Item Discount– Percent Off Item Discount– Amount Off Item Discount– Fixed Price Item Discount– Multiplier Shipping Discount- Percent Off Shipping Discount- Amount Off Shipping Discount - Fixed Price Order Discount - Percent Off Order Discount - Amount Off Order Discount - Fixed Price	read-only
	The type of discount this promotion gives. This is set during item creation. (Note that two promotions can have different values for `type` and the same values for `discountType`. See the `discountType` property.)
`uses`	int	any positive integer, zero	none
(display name: Number of uses allowed per customer)	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. The enumerated list from which this property value is first set (when the promotions is created via the ACC) is defined in `/atg/commerce/pricing/pricingModels.xml`, which is located at `<ATG2007.3dir>/DCS/config/config.jar`. To alter the values in the enumerated list, you must change the values in `pricingModels.xml`. Note 1: 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 `oneUsePerOrder` property to `true`. Note 2: This property is ignored when the `global` property is set to `true`.
`version`	long	any long	hidden
(display name: Version)	Used by the SQL Repository to protect against data corruption caused by two different threads attempting to modify the same item the same time.

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 different issues to keep in mind when you are creating promotions for your site.

Check the “go live” dates of all promotions to prevent a promotion from taking effect before you’re ready for it. This is usually set in the ‘start date’ and ‘end date’ properties.
Note: When setting the “go live” dates of a promotion, be aware that a number of factors can cause the promotion to be unusable for x minutes after it is set to be active and to be usable for x minutes after it is set to expire, where x is determined by the schedule set for the pricing engine component.
Because it can be resource intensive to collect a user’s list of promotions, or pricing models, the session-scoped UserPricingModels component (class atg.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. 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 its globalPromotionsQuery property to query the Promotions repository for all promotions where the global property is set to true, and it does so every x minutes as defined by the schedule specified in its updateSchedule property. Once collected, the pricing models in UserPricingModels 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’s UserPricingModels. To prevent this situation, manually call the pricingModelHolder.initalizePromotions method when you add any new promotion (targeted or global). The initializePromotions method generates a new list of pricing models to store in the user’s UserPricingModels. (Note that the pricingModelHolder.initializePromotions method should be called after the pricingEngine.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 Public Pricing Interfaces and Classes and Default Pricing Engines sections.
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 (ones that a customer can use an infinite number of times during a specified time period). For example, if you put all sneakers on sale for a given week, make sure you create a scenario to remove the promotion at the end of the week.

ATG Commerce Programming Guide

Using PMDL Rules