Working with Promotions

About Promotions

You can apply promotions to your customers, such as by granting 100 free minutes, 2 GB of free data, or 2 free movie downloads, in the following situations:

On special dates, such as a customer's birthday or membership anniversary. See "Applying Promotions On Special Dates".
Events or actions that occur in BRM, such as a customer purchasing a product or successfully topping up an account balance. See "Applying Promotions for Special Events or Actions".

Applying Promotions On Special Dates

You specify whether customers qualify for a promotion based on a special date by adding a promotion tag and date to their account profile. For example, to apply a promotion on a customer's birthday, you could add the promotion tag BIRTHDAY and promotion date of June 15. On June 15, BRM could grant the customer 100 free minutes, 5 Gigabytes of free data, or so on.

BRM applies the promotions to your customers' accounts when the pin_apply_promotion utility is run. The utility searches through each account's profile for a promotion date that occurs on or before the current date. When it finds a match, it looks up the promotion event associated with the promotion tag and then rates the promotion event, which in turn grants the free resources.

To configure BRM to apply promotions on special dates:

When you create an account or modify an account profile, include a promotion tag and date.

The promotion data is stored in an account's /profile/specialdates object.
Create a promotion event (/event/promotion/ subclass) for each promotion that your company supports and then load the promotion events into the BRM database.

For example, you could create an /event/promotion/birthday storable class for applying birthday promotions. BRM uses this event for rating and applying the promotion to your customers' accounts.

For more information about:
- Creating custom events, see "Creating Service and Event Storable Classes" in BRM Developer's Guide.
- Loading custom events into the BRM database, see "load_event_map".
Map your promotion tags to the promotion events you created in step 2. See "Mapping Promotion Tags to Promotion Events".

The mappings are stored in the /config/event_promo_tag_map object.
Define the amount and type of free resources that BRM needs to grant your customers when rating each promotion event. To do so, define how to apply credits for each promotion event in your system-level or account-level charge offers and rates.
Optionally, customize how promotions are applied. See "Customizing Special Date, Event, or Action Promotions" in BRM Opcode Guide.
Run the pin_apply_promotion utility on a daily basis. See "pin_apply_promotion".

Mapping Promotion Tags to Promotion Events

To map promotion tags to promotion events:

Open the BRM_home/sys/data/config/config_event_promo_tag_map.xml file in a text editor.

The config_event_promo_tag_map.xml file contains sample mappings, but you can modify them to meet your business needs.

Add an <EVENT_MAP> array element for each promotion tag that you want mapped to a promotion event. Table 19-1 describes the elements in <EVENT_MAP>.

Table 19-1 Elements in config_event_promo_tag_map.xml

Element	Description
<PROMO_EVENT_TYPE>	The promotion event to rate.
<PROMO_TAG>	The name of the promotion tag.

The following sample content maps the BIRTHDAY promotion tag to the /event/promotion/birthday promotion event:

<ConfigObject>	
   <DESCR>Event Promo Tag Map Configuration</DESCR>
   <HOSTNAME>-</HOSTNAME>
   <NAME>Event Promo Tag Map</NAME>
   <PROGRAM_NAME>load_config</PROGRAM_NAME>
   <EVENT_MAP elem="0">
      <PROMO_EVENT_TYPE>/event/promotion/birthday</PROMO_EVENT_TYPE>
      <PROMO_TAG>BIRTHDAY</PROMO_TAG>
   </EVENT_MAP>
</ConfigObject>

Save and close the file.
Edit the load_config utility's configuration file (BRM_home/apps/load_config/pin.conf) to specify how to connect to the BRM database.
Load the config_event_promo_map.xml file into the BRM database:
```
load_config -d -v BRM_home/sys/data/config/config_event_promo_tag_map.xml
```
See "load_config" in BRM Developer's Guide for more information.
Stop and restart the Connection Manager (CM).
Verify that the mappings were loaded properly by running the following command:
```
load_config -w "event_promo_tag_map" config_event_promo_tag_map_out.xml
```

Applying Promotions for Special Events or Actions

You can configure BRM to apply promotions for special events or actions by associating BRM event types with your promotions. For example, you could specify that all /event/billing/product/action/purchase events qualify for a promotion. In this case, every time customers purchase a new product, BRM could grant them 5 gigabytes of free data, 1 free movie download, or so on.

You implement these types of promotions by using the BRM event notification system. When a specified BRM event occurs, the event notification system triggers a call to the PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT opcode which in turn looks up the promotion event associated with the BRM event. For example, it could look up that /event/billing/product/action/purchase events are associated with the /event/promotion/subscribe_offer promotion event. BRM then rates the promotion event, which grants the free resources.

To configure BRM to apply promotions for special events or actions:

Create a promotion event (/event/promotion/ subclass) for each promotion that your company supports and then load the promotion events into the BRM database.

For example, you could create an /event/promotion/subscribe_offer storable class. BRM uses this event for rating and applying the promotion to your customers' accounts.

For more information about:
- Creating custom events, see "Creating Service and Event Storable Classes" in BRM Developer's Guide.
- Loading custom events into the BRM database, see "load_event_map".
Configure the event notification system to trigger calls to the PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT opcode when a BRM event occurs. See "Configuring Event Notification for Promotions".
Map BRM events to the promotion events you created in step 1. See "Mapping BRM Events to Promotion Events".

The mappings are stored in the /config/event_promo_map object.
Define the amount and type of free resources that BRM needs to grant your customers when rating each promotion event. To do so, define how to apply credits for each promotion event in your system-level or account-level charge offers and rates.
Optionally, customize how promotions are applied. See "Customizing Special Date, Event, or Action Promotions" in BRM Opcode Guide.

Configuring Event Notification for Promotions

To configure event notification for promotions, you must map each BRM event to which you want to apply promotions to the PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT opcode. For more information about event notification, see "Using Event Notification" in BRM Developer's Guide.

To configure event notification for promotions:

Open the BRM_home/sys/data/config/pin_notify file in a text editor.
Add an entry for each BRM event that should trigger calls to opcode 9075 (the number for the PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT opcode).

For example, to trigger calls to PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT whenever customers successfully top up their account balances, purchase a new product, or create an account profile, you would add the following lines:
```
# Event Notification for Promotions
9075    0       /event/billing/topup
9075    0       /event/billing/product/action/purchase
9075    0       /event/notification/profile/create
```
Save and close the file.
Load your pin_notify file into the BRM database by using the load_pin_notify utility:
```
load_pin_notify BRM_home/sys/data/config/pin_notify
```
See "load_pin_notify" in BRM Managing Customers for more information.
Stop and restart the Connection Manager (CM).

Mapping BRM Events to Promotion Events

To map BRM events to promotion events:

Open the BRM_home/sys/data/config/config_event_promo_map.xml file in a text editor.

The config_event_promo_map.xml file contains sample mappings, but you can modify them to meet your business needs.

Add an <EVENT_MAP> array element for each BRM event that you want mapped to a promotion event. Table 19-2 describes the elements in <EVENT_MAP>.

Table 19-2 Elements in config_event_promo_map.xml

Element	Description
<EVENT_TYPE>	The BRM event.
<FIELD_NUM>	The field number defined in the BRM_home/include/pin_flds.h file. For example, you would use field number 601 for PIN_FLD_LABEL. Note: This applies to fields with a data type of PIN_FLDT_STR only.
<FIELD_VALUE>	The value of the field specified in FIELD_NUM.
<PROMO_EVENT_TYPE>	The promotion event.

The following sample content maps the /event/billing/topup event to the /event/promotion/topup promotion event:

<ConfigObject>	
   <DESCR>Event Promo Map Configuration</DESCR>
   <HOSTNAME>-</HOSTNAME>
   <NAME>Event Promo Map</NAME>
   <PROGRAM_NAME>load_config</PROGRAM_NAME>
   <EVENT_MAP elem="0">
      <EVENT_TYPE>/event/billing/topup</EVENT_TYPE>
      <FIELD_NUM>55</FIELD_NUM>
      <FIELD_VALUE>Topup Event (acct)</FIELD_VALUE>
      <PROMO_EVENT_TYPE>/event/promotion/topup</PROMO_EVENT_TYPE>
   </EVENT_MAP>
</ConfigObject>

Save and close the file.
Edit the load_config utility's configuration file (BRM_home/apps/load_config/pin.conf) to specify how to connect to the BRM database.
Load the config_event_promo_map.xml file into the BRM database:
```
load_config -d -v BRM_home/sys/data/config/config_event_promo_map.xml
```
See "load_config" in BRM Developer's Guide for more information.
Stop and restart the Connection Manager (CM).
Verify that the mappings were loaded properly by running the following command:
```
load_config -w "event_promo_map" config_event_promo_map_out.xml
```