Promotion Repository Item Properties

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..

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.”

Note: This property is no longer used, and is maintained only for backward compatibility.

allowMultiple

(display name: Give to a customer more than once)

Boolean

true or false

none

Determines whether the promotion can be given to a customer only once. If set to false, the system grants 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 is granted the promotion.

Note: This property is ignored if the global property is set to true.

beginUsable

timestamp

any date

none

(display name: Usage start date)

The date that the promotion becomes effective. Used when the relativeExpiration property is set to false.

Together with the endUsable date, defines the period within which the promotion is valid, including global promotions. If both values are null, the promotion is always valid.

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

The type of discount this promotion gives.

Note: This property is no longer used, and is maintained only for backward compatibility.

displayName

string

any string

none

(display name: Name)

Specifies the name visible in the user interface.

enabled

(display name: Enabled)

Boolean

true or false

none

Specify true to enable the promotion. If enabled, the promotion takes effect according to the specified usage period. If disabled, the promotion never takes effect regardless of the usage 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 an order, 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

timestamp

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.

Together with the beginUsable date, defines the period within which the promotion is valid. If both values are null, the promotion is always valid.

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 can receive the promotion. If this property is true, and the global property is false, then anonymous visitors and registered visitors can receive the promotion. In both cases, the visitors must meet any other conditions specified by the promotion in order to receive it.

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 applied an unlimited number of times, to all visitors (including anonymous visitors), for use on an unlimited number of orders, during the specified usage period, regardless of the values set for the following properties:

-- allowMultiple

-- startDate

-- endDate

-- 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

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 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.

pricingCalculatorService

enumerated

a calculator

none

(display name: Pricing 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.

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 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.

relativeExpiration

(display name: Usage Period)

Boolean

true or false

none

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

Determines the usage period in minutes for the promotion. Used when the relativeExpiration property is set to true.

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 activePromotions profile property. The expiration date and time is then determined by the number of minutes in timeUntilExpire to the current time.

Note: This property is ignored when the global property is set to true.

type

(hidden)

enumerated

Oracle ATG Web Commerce 10 and later versions:

Item Discount
Shipping Discount
Order Discount

Versions prior to Oracle ATG Web Commerce 10:

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.

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.

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 oneUsePerOrder property to true.

Note: 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.

parentFolder

promotionFolder

any promotionFolder item

none

(display name: Parent Folder)

The parent folder of the promotion.

sites

set

set of siteConfiguration items

none

(display name: Sites)

The siteConfiguration item or items with which the promotion is associated. Pricing engines should only evaluate promotions that include the current site context, or where both the sites and siteGroups properties are null.

siteGroups

set

set of siteGroup items

none

(display name: Site Groups)

The siteGroup or groups with which the promotion is associated. Pricing engines should only evaluate promotions whose siteGroups properties include the current site context or where sites and siteGroups are null.

template

string

any string representing a template name

none

(display name: Template)

The template with which the promotion is associated. Promotions templates are used in Oracle ATG Web Commerce Merchandising; see the ATG Merchandising Guide for Business Users.

templateValues

map

Map of template placeholder values

none

(hidden)

Placeholder values are used to build the PMDL from a template; see Adding New Promotions Templates.

uiAccessLevel

int

0 or 1

none

(hidden)

The value in this field identifies whether or not the promotion is read-only (0) or writeable (1).

pmdlVersion

int

1 or 2

none

(hidden)

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, and endUsable 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 nonglobal promotions).

  • 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. 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 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 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 and endUsable dates are set correctly.

Copyright © 1997, 2012 Oracle and/or its affiliates. All rights reserved.

Legal Notices