Configuring Product Specification Attributes for Pricing Components

About Product Specification Attributes for Pricing Components

You can use product specification attributes on pricing components to save extra information that may be useful to external applications.

In the TM Forum data model, a product specification is a collection of attributes, or product specification characteristics, that describe a product. Although BRM and PDC do not use TM Forum product specifications or act on product specification attributes, you can choose to store the attribute information in the BRM database so that it can be queried and used by external applications.

In BRM, you create product specification attributes in a configuration template file and then provide values for them while creating your pricing components in PDC or in XML.

For example, if your external enterprise product catalog has an attribute for tracking the lifecycle status of a charge offer with relevant values beyond the two statuses offered by PDC (draft or promoted), you can use a product specification attribute to store that status. Your enterprise product catalog can then query or update that status as needed.

At a high level, the steps for using product specification attributes with pricing components are as follows:

Create product specification attributes in a configuration template file. See "Configuring Product Specification Attributes for Pricing Components".
Import the template file by using the ImportExportPricing utility. See "Importing Pricing and Setup Components".
Create pricing components in PDC or XML, including the product specification attribute values. See "Using Product Specification Attributes in Pricing Components".
When you create pricing components in PDC, the UI validates the values against the configuration template file.

When you import pricing components from an XML file using ImportExportPricing, the utility validates the values in the pricing component files against the configuration template file. The import fails if any values don't conform to the configuration file. See "About Validating Product Specification Attributes for Pricing Components".

Afterwards, if you need to change your product specification attributes, follow the instructions in "Modifying Product Specification Attribute Definitions".

Configuring Product Specification Attributes for Pricing Components

You configure product specification attributes for pricing components in a ProductSpecCharacteristicTemplate.xml configuration file and import them along with other pricing setup components using the ImportExportPricing utility.

PDC provides a sample XML file for product specification attributes in the PDC_home/apps/Samples/Examples directory, where PDC_home is the directory in which you installed PDC.

In the configuration file, you use a separate template entry for each pricing component type. You can create template entries for the pricing components listed in Table 36-1.

Table 36-1 Pricing Components That Support Product Specification Attributes

Pricing Component	pricingObjectType Value
Charge offer	CHARGE_OFFERING
Discount offer	ALTERATION_OFFERING
Chargeshare offer	DISTRIBUTION_OFFERING
Bundle	BUNDLED_PRODUCT_OFFERING
Package	PACKAGE_OBJ

You define the following elements for each attribute:

name: The name of the attribute as it will appear when defining the pricing component. The name can be in any language using UTF-8 format.
type: The type of value for the attribute. Can be:
- ANY
- BOOLEAN
- DATE
- NUMBER
optional: Whether the attribute is optional (true) or not (false).
values: A configured list of possible values for the attribute. If you provided values here, the import of pricing components will fail if an attribute contains a value that was not defined here. If you don't provide values here, the pricing components can include any value that matches the type. The values can be in any language using UTF-8 format.
description: A description of the attribute. The description can be in any language using UTF-8 format.
cardinality: Whether only one value can be specified for the attribute when creating the pricing component (SINGLE), or multiple values can be specified (MULTIPLE).

The following example shows the XML file to create two lifecycle status attributes for a charge offer:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cim:ConfigObjects xmlns:cim="http://xmlns.oracle.com/communications/platform/model/Config">
    <productSpecCharacteristicTemplates xmlns:cim="http://xmlns.oracle.com/communications/platform/model/Config">
        <name>Charge Offer Product Specification Attribute Template</name>
        <internalId>1234</internalId>
        <priceListName>Default</priceListName>
        <obsolete>false</obsolete>
        <pricingObjectType>CHARGE_OFFERING</pricingObjectType>
        <productSpecCharacteristics>
            <name>Status</name>
            <type>ANY</type>
            <optional>true</optional>
            <values>Draft</values>
            <values>Test</values>
            <values>Release</values>
            <values>Suspend</values>
            <values>Retired</values>
            <description>Extended lifecycle status for the charge offer.</description>
            <cardinality>SINGLE</cardinality
        </productSpecCharacteristics>
        <productSpecCharacteristics>
            <name>Allowed Locations</name>
            <type>ANY</type>
            <optional>true</optional>
            <values>ASIA</values>
            <values>USA</values>
            <values>EUROPE</values>
            <values>CANADA</values>
            <values>OCEANIA</values>
            <description>Locations where the charge offer can be sold.</description>
            <cardinality>MULTIPLE</cardinality
        </productSpecCharacteristics>
    </productSpecCharacteristicTemplates>
</cim:ConfigObjects>

Using Product Specification Attributes in Pricing Components

When creating pricing components in PDC or XML, you can use product specification attributes configured in the ProductSpecCharacteristicTemplate.xml file.

In PDC, any product specification attributes you configure in the template file appear in the Product Spec Characteristic Attributes (Custom Attributes) section for charge offers, discount offers, chargeshare offers, bundles, and packages. You can add or update the values.

In the XML file for your pricing component, use the productSpecCharacteristic element to add an attribute, and provide the name and a value element for each attribute. For example:

<chargeOffering externalID="1234">
      <name>ChargeOfferWithExtendedAttribute</name>
      <internalId>5678</internalId>
      <pricingProfileName>Product Offering</pricingProfileName>
      <priceListName>Default</priceListName>
      <obsolete>false</obsolete>
      <timeRange>0/inf</timeRange>
      <productSpecName>TelcoGsmTelephony</productSpecName>
      <productSpecCharacteristic>
         <name>Status</name>
         <value>Test</value>
      </productSpecCharacteristic>
      <productSpecCharacteristic>
         <name>Allowed Locations</name>
         <value>ASIA</value>
         <value>USA</value>
         <value>EUROPE</value>
      </productSpecCharacteristic>
...

Keep the following in mind when defining values for product specification attributes:

You can only use the attributes configured for the template with the same pricing type as the pricing component you are creating. In the example above, because you are creating a charge offer, all of the product specification attributes must come from the template configured for the CHARGE_OFFERING pricing type.
Values are case sensitive.
The value in the name must match one of the attributes you configured in the template file.

The valid values are determined by the type and value elements configured for the attribute in the template file. Table 36-2 describes the supported types.

Table 36-2 Supported Value Types

Configured Type	Supported Values
ANY	UTF-8 strings in any language. If any value elements were configured for the attribute in the template file, only those values are supported.
DATE	Dates in format YYYYMMDD. If any value elements were configured for the attribute in the template file, only those values are supported.
BOOLEAN	true or false
NUMBER	Numbers 0-9. Decimals are supported, using either a period or comma as a decimal separator, according to your localization settings. If any value elements were configured for the attribute in the template file, only those values are supported.

See "About Validating Product Specification Attributes for Pricing Components".

Caution:

After importing your pricing components, if you update them using ImportExportPricing, you must include all product specification attributes names and values in the definition, regardless of whether you are updating them. Any product specification attributes you do not include when you import the updated file will be removed from the pricing component.

About Validating Product Specification Attributes for Pricing Components

The validation method for product specification attributes depends on where you create pricing components.

When you create pricing components in PDC, the UI validates the values of product specification attributes against the attribute configuration template. Error messages are displayed for any failed validations.

When you import pricing components using the ImportExportPricing utility, the utility validates that:

A template exists in the configuration file for the pricing component type.
The name of an attribute appears in the template for the pricing component. For example, an attribute specified for a discount offer must appear under the template for the ALTERATION_OFFERING price type.
Each attribute appears only once in the pricing component definition.
The value of the attribute matches the type element configured in the template. For example, an attribute with the BOOLEAN type can only have true or false as values.
The value of the attribute matches one of the value elements configured in the template if the attribute configuration contains a specified list of values.
A value is provided for any attributes where the optional element is set to false.

The UI and the utility only validate against the configuration file. They do not validate based on the meaning of the attributes. For example, the UI or utility cannot validate that the start date is earlier than the end date in product specification attributes for start and end dates, or that a location in a product specification attribute for allowed locations matches the currency defined for a pricing component.

You can optionally implement custom validations for charge offers, discount offers, and bundles created in XML using the following pricing policy opcodes:

PCM_OP_PRICE_POL_VALID_PRODUCT
PCM_OP_PRICE_POL_VALID_DISCOUNT
PCM_OP_PRICE_POL_VALID_DEAL

See "About the PREP and VALID Opcodes" in BRM Developer's Guide for information about using VALID opcodes.

Modifying Product Specification Attribute Definitions

If you want to modify any existing product specification attribute definitions, you must do the following:

Export, update, and then re-import the attribute configuration template.
Export, update, and then re-import your pricing components, which have been modified to comply with the updated attribute configuration template.

Following this procedure ensures that any changes made to your attribute definitions do not invalidate the pricing components already stored in PDC.

The following example shows how to modify the attribute definitions for charge offers. You can use a similar procedure to modify attribute definitions for discount offers and charge share offers.

Export all charge offers from PDC. For example:
```
ImportExportpricing -export MyChargeOffers -config CHARGE_OFFERING
```
In this example, all charge offers are exported to the MyChargeOffers_export_pricing.xml file.
Export all attribute configuration template objects from PDC. For example:
```
ImportExportPricing -export ProductSpecCharacteristicTemplate -config PSCTEMPLATE
```
In this example, all attribute configuration template objects are exported to the ProductSpecCharacteristicTemplate_export_config.xml file.
Update your attribute configuration template XML file according to the information in "Configuring Product Specification Attributes for Pricing Components".
Import your modified attribute configuration template XML file into PDC. For example:
```
ImportExportPricing -import -config ProductSpecCharacteristicTemplate_export_config.xml -ow
```
Update the charge offers in your MyChargeOffers_export_pricing.xml file to comply with the latest attribute configuration template.

Import your updated charge offers into PDC. For example:

ImportExportPricing -import -pricing MyOffers_export_pricing.xml -ow