The sections that follow describe how to expose and use repository item properties as part of your promotions template.

Note: If creating a template using a custom discount type, make sure the PMDL in that template sets the discount-type attribute correctly.

The item-properties section of the PMDT file complements the ui-description and allows you to set promotion properties using the place-holder-value attributes of the template elements. The property statements are based around a separate grammar from that used in the UI portion of the template.

The item-properties section of the template for a beginUsable and endUsable looks like the following sample. Note the $ marking where place-holder-value information is inserted:

    <property name="beginUsable">
      ${beginUsableValue}
    </property>

    <property name="endUsable">
      ${endUsableValue}
    </property>

Displaying Static Values in Templates

The default behavior for generating a display name for a property is:

Displaying Dynamic Properties in Templates

The content-source element dynamically obtains information for display in the template. One common use is populating combo boxes (see the Product Set Criteria Elements section), but you can use it to populate any user interface element, provided that the content source’s Nucleus component provides the correct output.

For example, consider this template XML:

<comboBox id="discountType">
  <content-source path="/atg/remote/promotion/template/contentSource/
CustomDiscountListContent">
    <attribute-value-reference name="calculatorType"
 element-id="calculatorType"/>
  </content-source>
</comboBox>

The path attribute is required, and identifies the location of the Nucleus component that returns the dynamic information.

You can use the optional child attribute element to specify parameters to pass to the Nucleus component. Parameter values are either set explicitly or obtained from the user input to another field in the template user interface. The component returns a ContentState object that contains the information used to populate the field.

For example, the attribute-value-reference element in the code shown above tells the content source to watch a second user interface element, that has the element-id="calculatorType". The user’s currently selected value for the calculatorType is assigned the name calculatorType and sent to the CustomDiscountListContent component. The component obtains a valid discount list for that calculatorType.

If the user changes the selected calculatorType, the new value is sent to the component to obtain an updated discount list for display.

Content source Nucleus components should implement the atg.remote.promotion.template.contentSource.java interface. See the ATG Platform API Reference for information on this interface.

Using an Asset Picker in a Promotions Template

If you have included repository item properties in your template, you need to provide a map to the Asset Picker editor needed to manipulate that property. The asset picker is a Flex RepositoryItemSetEditor component used in many Oracle ATG Web Commerce applications (see the ATG Business Control Center Administration and Development Guide for general information on asset pickers).

The asset picker requires three pieces of information:

To provide this information, configure the assetPickerPropertyMap and the assetPickerRepositoryMap components in the PSCExpressionContext component.

The assetPickerRepositoryMap property provides a map of properties to their repositories. The assetPickerPropertyMap property provides a map of properties to their repository item types. If a property appears in this map, the promotions user interface uses the asset picker editor for that property; otherwise, it defaults to a simple text editor.

Whether or not the asset picker allows multiple selections depends on the operator the user selects; for example, “is” allows only single selection, but “is one of” permits multiple selections.

If a property is included in the assetPickerPropertyMap, the promotions expression editor displays an asset picker for that property on the right hand side of the product set criteria expression, using the value of the map as the asset type. If an entry for the property is also in the assetPickerRepositoryMap, the value of this map is used as the repository path for the asset picker.

If a property is in the assetPickerPropertyMap but not in the assetPickerRepositoryMap, then the asset picker defaults to using the RepositoryPropertyDescriptor for that property to determine the repository to use.

This sample shows configuration for the two properties:

assetPickerPropertyMap+=\
  item.auxiliaryData.catalogRef.sites=siteConfiguration

assetPickerRepositoryMap+=\
  item.auxiliaryData.catalogRef.sites=/atg/multisite/SiteRepository

The resulting user interface would display the Sites property of the sku repository item in an asset picker. The picker would use the siteConfiguration asset type and SiteRepository.

Automatic Property Filtering in Templates

Oracle ATG Web Commerce repository items used in promotions tend to have many properties that are not useful as promotion criteria. Therefore, the list of properties is filtered by default.

If you add custom properties to your Oracle ATG Web Commerce repository, note that category properties do not appear in the PSC; only product and SKU properties are exposed.

The /atg/remote/promotion/expreditor/psc/PSCExpressionContext component includes the excludedProperties property. The value for this property can end in * to exclude all sub-properties of a property. Note that a * does not exclude the referenced property itself, but only its sub-properties. The actual property must be excluded separately. For example:

excludedProperties+=\
  item.auxiliaryData.productRef.template.*

The example above excludes all sub-properties of the template property, but does not exclude the template property itself. To exclude the template property, use the following configuration:

excludedProperties+=\
  item.auxiliaryData.productRef.template\
  item.auxiliaryData.productRef.template.*

The PSCPropertyChoiceExpression class on which the PSCExpressionContext component is based extends the PricingPropertyChoiceExpression class; therefore, it inherits a standard filtering mechanism which by default filters out properties marked as expert = true or queryable = false in the repository definition. You can override this behavior using the mandatoryProperties property of PSCExpressionContext.

Note that the mandatoryProperties property does not support wildcards; all mandatory properties must be specified explicitly. This example shows mandatoryProperties in use:

mandatoryProperties+=\
  item.auxiliaryData.productRef.ancestorCategoryIds

This configuration results in the ancestorCategoryIds property being included, even though this property is marked as expert in the repository.