13 Setting Up Real-Time and Pipeline Pricing and Rating

This chapter describes how to configure pricing data for the real-time rating and Oracle Communications Billing and Revenue Management (BRM) Pipeline Manager.

Topics in this document:

• About Configuring Price List Data

• Setting Up Resources or Balance Elements

• Mapping Pipeline Manager Currencies and Real-Time Rating Currencies

• Setting Up Offer Profiles

• Setting Up Ratable Usage Metrics (RUMs)

• Mapping Event Types to RUMs

• About Mapping Services

• Mapping Service Codes and Service Classes

• Mapping Events and Services

• Mapping Usage Classes

• Mapping Usage Types

• Adding Customer Balance Impact Data to EDRs

• Modifying and Loading the EDR Container Description

• Dropping or Upgrading Incomplete Calls after Changing the EDR Container Description

• About Serviceless Accounts as Charge Sharing Owners

• Mapping Subscription Services in the Pipeline Manager Database

• Setting Up Batch Rating to Assign Items Based on Event Attributes

About Configuring Price List Data

Before creating your price list, you must do the following tasks to configure price list data:

• Create resources. See "Setting Up Resources or Balance Elements".

• Set up offer profiles. See "Setting Up Offer Profiles".

• Create ratable usage metrics (RUMs). See "Setting Up Ratable Usage Metrics (RUMs)".

• Map event types to RUMs. See "Mapping Event Types to RUMs".

• Specify which events you must rate. See "Mapping Events and Services".

• Map the external data to the internal usage class. See "Mapping Usage Classes".

• Define and map the usage types. See "Mapping Usage Types".

Setting Up Resources or Balance Elements

Real-time rate plans and pipeline rate plans each use a different set of resources. See the following topics:

• Setting Up Resources for Real-Time Rating

• Setting Up Pipeline Manager Resources or Balance Elements

  Note:

  You must use the same resource names for real-time and batch pipeline resources.

Setting Up Resources for Real-Time Rating

If you are using Pricing Center, you must use the Resource Editor in Pricing Center to create resources before you create a price list. You can create currency and noncurrency resources.

When you create resources, you define the following:

• The resource name, such as US Dollars.

• The resource ID, such as 840. Currency resource IDs are defined in an ISO standard.

• The rounding value. For example, to round US dollars to cents, specify a rounding value of two places after the decimal point.

  Note:

  Resource Editor sets rounding only for A/R actions such as adjustments and refunds. To set rounding for rating, discounting, and taxation as well as A/R, configure rounding in the pin_beid file. See "Configuring Resource Rounding".

• How to round additional numbers beyond the rounding value:

  • Up: For example, 10.151 rounds to 10.16.

  • Down: For example, 10.159 rounds to 10.15.

  • Nearest: If the additional digit is 0-4, the last significant digit remains the same. If the additional digit is 5-9, the last significant digit is rounded up. For example, 10.144 rounds to 10.14 and 10.145 rounds to 10.15.

  • Even: If the additional digit is 0-4, the last significant digit remains the same. If the additional digit is 6-9, the last significant digit is rounded up. If the additional digit is 5, the last significant digit is rounded to the nearest even digit. For example, if rounding is set to two significant digits, 10.155 rounds to 10.16 and 10.165 rounds to 10.16.

• For currency resources, you also define the error tolerance and the abbreviations and symbols used for display, such as $.

• The order in which to consume resource sub-balances. For example, if a customer's balance contains free minutes with different validity periods, you specify which minutes to use first, according to the starting validity date or ending validity date.

Setting Up Pipeline Manager Resources or Balance Elements

If you are using Pricing Center or Oracle Communications Pricing Design Center (PDC), Pipeline Manager resources or balance element IDs must match other BRM resources or balance element IDs. For example, when defining pipeline charges, you use BRM resources or balance element IDs, such as US Dollars (840). Pipeline Manager resources or balance elements can be mapped to other BRM resources or balance elements.

Defining Currencies

You must define all valid currencies before setting up currency balance elements.

You define Pipeline Manager currencies in Pricing Center, Oracle Communications Pipeline Configuration Center (PCC), or PDC.

You must also configure the DAT_Currency module. This module converts currency symbols to numeric values and retrieves balance element rounding rules, using data from /config/beid objects in the BRM database.

Defining a Resource or Balance Element

Resources in Pricing Center or PCC and Balance Elements in PDC are arbitrary measurement values for which a separate charge can be calculated. You can define two types of balance elements: Money and Other. Money balance elements are based on a defined currency. Other balance elements are noncurrency balance elements, such as duration or loyalty points.

You define Pipeline Manager balance elements in Pricing Center, PCC, or PDC.

Defining Currency Exchange Rates

You must set up an exchange rate for each currency you support for rating. Exchange rates specify the rate for converting one currency into another.

Call details records (CDRs) can come from multiple networks in different countries, which use different currencies. When you use exchange rates, you can store up to three charge packets with different currencies in a single EDR. The currency types are:

• Rating currency: The currency defined in the charge and pricing.

• Billing currency: The currency associated with a specific customer, network operator, and so forth for billing and invoicing.

• Home currency: The Pipeline Manager system-wide currency.

You convert currencies from the rating currency to the billing currency, the home currency, or both.

You define exchange rates in Pricing Center or PDC. Each exchange rate includes the following data:

• The currency to convert from.

• The currency to convert to.

• The conversion rate.

• The date from which the conversion rate is valid.

To implement currency conversion, you configure the FCT_ExchangeRate module and the DAT_ExchangeRate module.

When you configure FCT_ExchangeRate, you specify the exchange rate conversion mode by setting the Mode entry to Normal or Reverse. In Normal mode, the exchange rate is the multiplier to convert the From Currency to the To Currency. In Reverse mode, the exchange rate is the multiplier to convert the From Currency to the To Currency and the divisor to convert the To Currency back to the From Currency.

For example, suppose the exchange rate to convert from EUR to USD is defined as 2.0. One pipeline converts EUR to USD with Mode set to Normal and the another pipeline converts USD to EUR with Mode set to Reverse. In Normal mode, the exchange rate 2.0 is the multiplier to convert from EUR to USD (EUR * 2.0 = USD). In Reverse mode, the exchange rate 2.0 is the divisor to convert from USD to EUR (USD / 2.0 = EUR). If Reverse mode was not used, you would define another exchange rate 0.50 to convert from USD to EUR.

To update conversion rates, you use the DAT_ExchangeRate module Reload semaphore. The new exchange rates overwrite the old rates.

About currency exchange validity dates

You can use the FCT_ExchangeRate module to configure how to define the validity date for currency conversion for two cases.

• Use the RatingDateBilling registry entry to convert from the rating currency to the billing currency.

• Use the RatingDateHome registry entry to convert from the rating currency to the home currency.

You can specify a different value for the conversion to the billing currency and the home currency. For example, the validity date for converting the rating currency to the billing currency is usually the system time. The validity date for converting the rating date to the home currency is usually the CDR date.

For both registry entries, the values are:

• SYSTEM. The system time.

• FILE. The time that the file that includes the CDR was created (the file header time stamp).

• CDR. The time that the CDR was generated.

• NONE. (default).

  Note:

  If you specify RatingDateBilling in addition to the RatingDateHome and HomeCurrency parameters, it converts the currency to the home currency only.

Mapping Pipeline Manager Currencies and Real-Time Rating Currencies

Currencies are stored as strings for Pipeline Manager and as numbers for real-time rating. You must map Pipeline Manager currency IDs to real-time rating currency names. To do so, you create a list of currencies in the FCT_BillingRecord module registry.

Setting Up Offer Profiles

If you are using Pricing Center, set up each offer profile in the following way:

Note:

If you are using PDC, see the discussion about configuring policy specifications in PDC Creating Product Offerings.

1. Provide a unique name for the offer profile.

   Note:

   When setting up a product or a discount for an existing offer profile, use the offer profile name as the provision tag of the product or discount.

   Alternately, when you create an offer profile for an existing product or discount, use the provisioning tag of the product or discount as the name for the offer profile.

2. Configure a set of policy labels that define the currency or noncurrency resource and the quality of service in rate tiers.

   For example, you can define a policy label called Fair Usage for a noncurrency resource (such as Megabytes Used, whose resource Id is 100009). Set profile status levels based on predefined quality of service. The gradation may be as follows:

   • Low QoS for usage between 0 and 2.5 Megabytes

   • Medium QoS for usage between 2.5 and 5 Megabytes

   • High QoS for usage above 5 Megabytes

   Example 13-1 shows the contents of one sample policy label.

Example 13-1 Sample Policy Label

<policy_label>
   <label>Fair Usage</label>
   <resource_name>Megabytes Used</resource_name>
   <resource_id>100012</resource_id>
   <unit> 1 </unit>
   <tier>
       <tier_start_range>0</tier_start_range>
       <tier_end_range>2.5</tier_end_range>
       <status_label>High Qos</status_label>
       </tier>
    <tier>
       <tier_start_range>2.5</tier_start_range>
       <tier_end_range>5</tier_end_range>
       <status_label>Med Qos</status_label>
    </tier>
    <tier>
       <tier_start_range>5</tier_start_range>
       <status_label>Low Qos</status_label>
    </tier>
</policy_label>

Setting Up Ratable Usage Metrics (RUMs)

For background information about RUMs, see "About Ratable Usage Metrics".

Real-time rate plans and pipeline rate plans each use a different set of RUMs. See the following topics:

• About Setting Up Rums for Real-Time Rating

• Setting Up Pipeline Ratable Usage Metric (RUM) Groups

About Setting Up Rums for Real-Time Rating

If you are using Pricing Center, before you create your price list, you must define the RUMs available for rating. When you define RUMs, you define the following RUM attributes:

• The event type that can be rated by using the RUM (for example, Internet usage events). You can specify more than one RUM for an event type.

• The unit of measurement. For example, to rate duration, you might specify seconds or minutes. To measure bytes, you might specify megabytes or kilobytes.

• The RUM name (for example, “Duration," “Pages," or “Bytes"). The RUM name is displayed in Pricing Center.

• How to calculate the quantity. For example, to calculate the length of a session event, you subtract the time the event started from the time that the event ended:

  Event start: 7:00 p.m.

  Event end: 9:00 p.m.

  Event end - Event start = 2 hours

  This RUM is defined as follows:

  /event/session : Duration : PIN_FLD_END_T-PIN_FLD_START_T : second
  

  • The RUM name “Duration" appears in Pricing Center.

  • The duration is calculated by subtracting the start time from the end time.

  • The duration is calculated by using seconds.

To perform calculations, you can use simple arithmetic by using the following operators:

• +

• -

• *

• /

• (

• )

You can use three data types:

• PIN_FLDT_INT

• PIN_FLDT_DECIMAL

• PIN_FLDT_TSTAMP

You can use fields in a substruct, but you cannot use arrays.

Note:

The data used for the quantity calculation is stored in event object fields. For example, the event start and end times are stored in PIN_FLD_START_T and PIN_FLD_END_T. You must be familiar with events and event fields to specify quantity calculations.

To define the RUMs, you edit the pin_rum file and load it into the BRM database using the load_pin_rum utility. See "Creating Ratable Usage Metrics".

Creating Ratable Usage Metrics

To create RUMs, you edit the pin_rum file and then run the load_pin_rum utility to load the contents of the file into the /config/rum object in the BRM database.

Note:

The load_pin_rum utility needs a configuration (pin.conf) file in the directory from which you run the utility.

To create ratable usage metrics:

1. Edit the pin_rum file in BRM_Home/sys/data/pricing/example. The pin_rum file includes examples and instructions.

   Note:

   A RUM name can include a maximum of 255 characters.

   Note:

   The load_pin_rum utility overwrites existing RUMs. If you are updating RUMs, you cannot load new RUMs only. You must load complete sets of RUMs each time you run the load_pin_rum utility.

2. Save and close the pin_rum file.

3. Use the following command to run the load_pin_rum utility:

   load_pin_rum pin_rum_file
   

   If you do not run the utility from the directory in which the file is located, you must include the complete path to the file. For example:

   load_pin_rum BRM_Home/sys/data/pricing/example/pin_rum_file
   

   For more information, see "load_pin_rum".

4. Stop and restart the Connection Manager (CM). If necessary, stop and restart Pricing Center.

To verify that the pin_rum file was loaded, you can display the /config/rum object by using Object Browser, or use the robj command with the testnap utility.

Note:

Fold events cannot use custom RUMs; therefore, do not assign custom RUMs to fold events in any rate plans. Products configured with custom fold RUMs are rated incorrectly.

Setting Up Pipeline Ratable Usage Metric (RUM) Groups

RUMs are ways in which you can measure events, such as how long they last or how big they are. When you create RUMs, you give them names, such as Duration or Volume, and assign them a type, such as Duration, Event, or Normal.

Units of measurement (UoMs) are the names you give to units you will use to measure events, such as seconds or bytes.

A RUM group associates two or more RUMs together and associates a UoM with each RUM in the group.

When you rate events by using a RUM group, a separate charge packet is created for each RUM.

About Defining Units of Measurement (UoMs)

UoMs are the names you give to units you will use to measure events, such as seconds or bytes.

About Defining Ratable Usage Metrics (RUMs)

RUMs are types of event measurements that you define, such as duration or volume.

About Defining a RUM Group

A RUM group groups two or more RUMs together and associates a UoM with each RUM in the group.

Converting Units of Measurement

The UoM of an incoming EDR can be converted into a UoM needed for rating a particular service. For example, an EDR might include the usage amount in seconds, but the service is configured to charge by minutes. The FCT_UoM_Map module converts seconds to minutes, using rounding rules.

To configure UoM mapping:

1. Use Pricing Center or PCC to create a UoM map to convert UoMs. When you convert UoMs, you specify the following:

   • The RUM that uses the UoM.

   • The UoM to convert from.

   • The UoM to convert to.

   • The conversion factor. For example, use a factor of 1024 to convert kilobytes into bytes.

   • The rounding rule. The options are:

     • Nearest (N)

     • Always up (U)

     • Always down (D)

2. Configure the FCT_UoM_Map module.

Mapping Event Types to RUMs

If you are using Pricing Center for creating product offerings, you map event types to RUMs by using Pricing Center. However, you can edit the pin_usage_map file and load its content into the BRM database by running the load_usage_map utility. By doing so, you update the /config/usage_map/system object.

Note:

If you are using PDC, see the discussion about setting up the service-event map in PDC Creating Product Offerings.

Note:

The load_usage_map utility requires a configuration (pin.conf) file in the directory from which you run the utility.

1. Edit the pin_usage_map file in BRM_Home/sys/data/pricing/example. The pin_usage_map file includes examples and instructions.

   Note:

   The load_usage_map utility overwrites existing usage maps. If you are updating a set of usage maps, you cannot load new usage maps only. You must load complete sets of usage maps each time you run the load_usage_map utility.

2. Save the pin_usage_map file.

3. Use the following command to run the load_usage_map utility:

   load_usage_map pin_usage_map_file
   

   If you are not in the same directory as the pin_usage_map file, include the complete path to the file. For example:

   load_usage_map BRM_Home/sys/data/pricing/example/pin_usage_map_file
   

   For more information, see "load_usage_map".

4. Stop and restart the Connection Manager (CM). If necessary, stop and restart Pricing Center.

To verify that the data loaded correctly, display the /config/usage_map/system object by using Object Browser, or use the robj command with the testnap utility.

About Mapping Services

Incoming event data records (EDRs) from multiple switches often use different codes to represent the same service or supplementary service. To process EDRs, you must normalize that data by mapping external service codes to internal service codes, service classes, and usage classes. You also must map usage types so they can be added to EDRs.

• An internal service code represents a service such as voice or fax.

• An internal service class represents a variation on the service (for example, a GPRS quality of service (QoS) or a telephone service used only for emergency calls).

• An internal usage class represents a supplementary service (for example, call forwarding or a voice mail box). The data used for rating usage classes comes from the network.

• A usage type represents an attribute of a customer's account, such as an extended rating attributes (ERA), that is used in rating but which is not available from the network.

You define the internal codes and usage types in PCC. All of these are used to rate usage.

Note:

If you are using PDC, see the discussion about setting up service and event definitions in PDC Creating Product Offerings.

To create internal service mappings, you use PCC to set up the data that specifies how to map the external data to the internal codes. For example, you can specify that if the external service code is 011, the internal service code is TEL.

The mapping data you enter in PCC must match the syntax and format of the EDR input data.

About Creating Map Groups

You organize service codes, service classes, and usage classes in map groups. A map group specifies the set of services and usage scenarios to be used for rating by Pipeline Manager. You specify the name of the map group when setting up the pipeline modules.

You can create any number of map groups. When you have multiple map groups, you can use a different set of service mappings with different pipelines. For example:

• You rate services that use various EDR formats by setting up a pipeline for each format.

• If you rate roaming usage, you might set up three pipelines using these service mapping scenarios:

  • A retail rating pipeline that uses service mappings and usage scenarios relevant to your customer's accounts and services, such as friends-and-family calls, birthday calls, messaging services, and call forwarding.

  • Two pipelines (outcollect and incollect) for rating roaming usage that includes the services and usage scenarios described in your roaming agreements.

When you configure modules that use the map group, you enter the map group name in the registry. For example:

ServiceCodeMapping 
{
  ModuleName = FCT_ServiceCodeMap
  Module 
  { 
    Active = True 
    DataConnection = integrate.DataPool.Database
    MapGroup = serviceMapGroup
  }
} 

Note:

The map group name that you enter in the registry must exist in a map group configuration in the Pipeline Manager database.

Mapping Service Codes and Service Classes

To create service code and service class mappings, you use Pricing Center or PCC to specify which external data is used to determine the internal service codes and service classes. For example, you can specify that if the external service code is 011, the internal service code is TEL.

The mappings are based on the following data:

• External service code

• Usage class

• Location area indicator

• VAS event charge offer code

• Quality of service requested

• Quality of service used

• Record type

The mappings are stored in the IFW_SERVICE_MAP table. The mapping is performed by the FCT_ServiceCodeMap module.

In addition to mapping external service codes to internal service codes, you also map internal Pipeline Manager service codes to service types defined in the BRM database. These mappings are stored in the IFW_SERVICE database table.

The configuration in Table 13-1 shows the mapping for three services:

Table 13-1 Service Mapping Configuration

Pipeline Manager Service Code	BRM Service Type
TEL	/service/telco/gsm/telephony
SMS	/service/telco/gsm/sms
GPRS	/service/ip/gprs

Multiple Pipeline Manager service codes can be mapped to a single BRM service type. For the best performance, use as few service mappings as possible. For example, map the TEL, SMS, DATA, and FAX Pipeline Manager service codes to a single /service/telco/gsm BRM service type.

About Setting Up Service Mapping

To set up service mapping, do the following:

1. Create internal service codes and service classes in Pricing Center or PCC.

2. Map the external data to the internal service codes and service classes in Pricing Center or PCC.

3. Configure the FCT_ServiceCodeMap module.

   This module maps call data to service codes by using the data you entered in Pricing Center or PCC.

Mapping Events and Services

When you create your product offerings, the usage events that you specify must be associated with services in the Pipeline Manager IFW_REF_MAP table. This table specifies the service type to event type mapping so that services are associated with usage events. In addition, the IFW_REF_MAP database table also specifies the prefix for the data that identifies an account (for example, MSISDN or IMSI). See "Configuring Account ID Prefixes".

You can map multiple Pipeline Manager service codes to a single BRM service type. For example, you could map the TEL, SMS, DATA, and FAX Pipeline Manager service codes to a single /service/telco/gsm BRM service type.

The data is stored in the Pipeline Manager database.

Mapping an Event Type to a BRM Service Type

You can map one event type to a single BRM service type (that is, one event type to a Pipeline Manager service code). For example, to rate GPRS and GSM usage events, you map the services as shown in Table 13-2:

Table 13-2 Mapping an Event Type to a Service Type

Service	Event
/service/telco/gsm/telephony	/event/delayed/session/gprs
/service/ip/gprs	/event/delayed/session/telco/gsm

You enter service-to-event mappings in Pricing Center or PCC.

Mapping Multiple Event Types to a BRM Service Type

To rate multiple events for a service, you map multiple event types to a single service type. For example, to rate GSM and GSMTEL usage events for GSM Telephony service, you map the /event/delayed/session/telco/gsm and /event/delayed/session/telco/gsmtel event types to the /service/telco/gsm/telephony BRM service type.

Rating multiple events for a service involves the following:

1. Enabling the BRM Database to Store Multiple Event Types per Service

2. Populating the Event Types in the EDR Container

3. Configuring Output Streams Based on Service Code and Event Types for iRules

Enabling the BRM Database to Store Multiple Event Types per Service

To map multiple event types to a service type, you must update the one-to-one event type and service type mapping restriction in the BRM database. To do so, update the IFW_REF_MAP table.

By default, the IFW_REF_MAP table holds a PK_IFW_REM primary key constraint on the ID and the REF_OBJ columns. To update the one-to-one event type and service type mapping restriction in the BRM database, hold (or place) the PK_IFW_REM primary key constraint on the ID, REF_OBJ, and REF_PARAM columns.

Populating the Event Types in the EDR Container

When multiple event types are mapped to a service type, you must ensure that each event type is mapped to the appropriate service code.

You create an iScript or an iRule that will determine the correct event type for a service type in an EDR and populate the DETAIL.EVENT_TYPE field with the event type before passing the EDR through the following modules:

• FCT_Account module.

• FCT_AccountRouter module for the account router instance of the Pipeline Manager.

Configuring Output Streams Based on Service Code and Event Types for iRules

By default, the IRL_EventTypeSplitting iRule sends EDRs to separate output streams based on the service codes. When you configure multiple event types for a service type, you also map a service code to multiple event types. Therefore, you must update the IRL_EventTypeSplitting iRule and the data file to use the event types that are populated in the DETAIL.EVENT_TYPE field along with the service code to send EDRs to separate output streams.

To configure the output streams based on service codes and event types:

1. Update the IRL_EventTypeSplitting iRule to add a condition for checking the event types.

   The following IRL_EventTypeSplitting iRule sample shows the additional condition to check the event types:

   CONDITION:
   edrString(DETAIL.INTERN_SERVICE_CODE) =~ "${1}";
   edrString(DETAIL.EVENT_TYPE) =~ "${2}";

2. Edit the IRL_EventTypeSplitting.data file to include the event types. For example, the following entries map the GSM service code to the TELOutput and SMSOutput streams:

   GSM;/event/delayed/telco/gsm/telephony;TELOutput
   GSM;/event/delayed/telco/gsm/sms;SMSOutput

Example Procedure to Map Multiple Event Types to a Service Type

The following procedure is an example of how you map the /event/delayed/session/telco/gsm/telephony and /event/delayed/session/telco/gsm/sms event types to a single /service/telco/gsm service type.

1. Update the IFW_REF_MAP database table to hold (or place) the PK_IFW_REM primary key constraint on the ID, REF_OBJ, and REF_PARAM columns.

2. This step is optional. In Pricing Center or PCC, map the /service/telco/gsm service type to two internal service codes, GSM1 and GSM2.

3. Map the /event/delayed/session/telco/gsm/telephony and the /event/delayed/session/telco/gsm/sms event types to the /service/telco/gsm service type.

4. Update /config/event_map to map the /event/delayed/session/telco/gsm/telephony and the /event/delayed/session/telco/gsm/sms event types to the /service/telco/gsm service type.

5. Create a charge offer with a /service/telco/gsm service type and configure the following two event types:

   • /event/delayed/session/telco/gsm/telephony

   • /event/delayed/session/telco/gsm/sms

6. Map the /event/delayed/session/telco/gsm/telephony and the /event/delayed/session/telco/gsm/sms event types to the required pipeline charge.

7. Create an iScript called ISC_EventType.isc to contain the logic that populates the DETAIL.EVENT_TYPE field with the appropriate event type.

8. Update the IRL_EventTypeSplitting iRule to map each combination of service code and event type to an output stream as follows:

   GSM;/event/delayed/telco/gsm/telephony;TELOutput
   GSM;/event/delayed/telco/gsm/sms;SMSOutput
   GSM1;/event/delayed/telco/gsm/telephony;TEL1Output
   GSM1;/event/delayed/telco/gsm/sms;SMS1Output

Mapping Usage Classes

To create usage class mappings, you use Pricing Center or PCC to set up the data that specifies how to map the external data to the internal usage class. For example, you can specify that if the external supplementary service code for call forwarding is 41, the internal usage code is CW. In addition, you can use various EDR attributes to create variations on supplementary service for rating purposes. For example:

• Service code mapping. Use the usage class to create special virtual services and charge offers; for example, you can use the combination of telephony and call forwarding to create value-added services.

• ServiceClass-Mapping. Use the usage class to create special sub-services or quality of services (for example, service-level agreements).

• UsageScenario-Mapping. Use the usage class to map to impact categories.

• RateAdjustment. Use the usage class to provide discounts or adjustments in individual EDRs.

The mappings are based on the following data:

• External usage class

• Wholesale zone

• Tariff class and subclass

• Record type

• Connect type and Connect subtype, for example, anonymous, from another network, or direct

• Transit area code

• APN address when you use GPRS or UMTS technology

• SS (supplementary service) packet

The mapping is performed by the FCT_UsageClassMap module. You can configure this module to use a specific map group.

About Setting Up Usage Class Mapping

To set up usage class mapping:

1. Create internal usage classes in Pricing Center or PCC.

2. Map the external data to the internal usage classes in Pricing Center or PCC.

3. Configure the FCT_UsageClassMap module.

   This module maps usage classes by using the data you entered in Pricing Center or PCC.

Mapping Usage Types

A usage type represents an attribute of a customer's account that is used in rating but which is not available from the network (for example, closed usergroup calls, friends-and-family calls, VIP calls, and birthday calls). A usage type is dynamically determined by comparison patterns using the A number and the B number.

You define usage types to represent the following customer information in an EDR:

• An ERA, such as an ERA for Friends and Family calls.

  The usage type used for rating ERAs is determined by the call origin and destination data in the EDR. For example, if the destination number in an EDR matches the number on the account's friends-and-family list, the corresponding friends-and-family usage type is added to the EDR and is used during rating.

• A group to which a customer belongs.

  This usage type is used by filter sets to apply system charge offers and system discounts to a select group of customers. For example, if the EDR's DETAIL.CUST_A.CUST_SEG_LIST field matches one or more values you define, the corresponding usage type is added to the EDR.

  Note:

  You must create your own application to add data to the CUST_SEG_LIST field.

The usage types that you define are available to all rating scenarios.

Usage types are added to EDRs by running the IRL_UsageType iRule. This iRule performs no rating, it just adds the usage type to the EDR DETAIL block. You specify the rules for mapping EDR data to usage types in the files used by the IRL_UsageType iRule.

About Setting Up Usage Type Mapping

To set up usage type mapping:

1. Configure the IRL_UsageType iRule files. See the following sections:

   • Configuring the IRL_UsageType iRule for ERAs

   • Configuring the IRL_UsageType iRule for Filter Sets

   • Configuring the IRL_UsageType iRule for Both ERAs and Filter Sets

2. Configure the FCT_IRule module. See "Configuring the FCT_IRule Module to Run the IRL_UsageType iRule".

3. Create usage types in Pricing Center or PCC.

Configuring the IRL_UsageType iRule for ERAs

The IRL_UsageType iRule uses the following files in the pipeline_home/iScriptLib directory. The directory contains sample files.

• ISC_UsageType.isc. This file contains the iScript code that determines whether an EDR qualifies for a usage type. This script reads EDR fields and sets a series of variables. It then assigns a usage type to the EDR based on a mapping of variables to usage type.

  You can modify the ISC_UsageType.isc file to customize how to enter ERA data in Customer Center. For example, the following line uses a date format of YYYY.MM.DD:

  String strCallCombineYearMonth = "." + strCallMonth + "." + strCallDay; 
  

  You can change this iScript to support a date format of YYYY/MM/DD by doing the following:

  String strCallCombineYearMonth = "/" + strCallMonth + "/" + strCallDay; 
  

• IRL_UsageType.irl. This file contains the rules for mapping the variables to values. If the EDR contains an attribute that matches a variable, the value for that variable is set to Yes. Otherwise it is set to No.

• IRL_UsageType.data. This file contains the rules for assigning a usage type to the EDR. If the values of the variables match those specified in this file, the corresponding usage type is set in the EDR.

Configuration example

Note:

The sample configuration shows how to configure the iRule for ERAs only. It does not show how to configure the iRule for filter sets, which is done differently. For information, see "Configuring the IRL_UsageType iRule for Filter Sets" and "Configuring the IRL_UsageType iRule for Both ERAs and Filter Sets".

ISC_UsageType.isc

For ERAs, this file needs determination logic as shown in the following examples for the Friends and Family and Customer to Customer ERAs, respectively. This is in addition to the included ISC_UsageType Function.isc file, which is run when a condition is fulfilled.

isFriendsAndFamily = compareProductERAforProfileAttributes 
(profileNameFriendsFamily,"NUMBER", 
edrString(DETAIL.B_NUMBER), serviceType, EXACT_MATCH);

if  (edrNumDatablocks( DETAIL.CUST_A) > 0 and 
edrNumDatablocks(DETAIL.CUST_B) > 0)
isCustomerToCustomer = "Y";

IRL_UsageType.irl

The following example shows the rules (conditions) for mapping variables to values for all ERAs. It also shows the result placeholder for the usage type. Each number corresponds to a position in the IRL_UsageType.data file.

CONDITION:
isRoaming =~ "${1}";
isInternational =~ "${2}";
isHomeRegion =~ "${3}";
isCustomerToCustomer =~ "${4}";
isSameClosedUserGroup =~ "${5}";
isSameCorporateAgreement =~ "${6}";
isSameCustomer =~ "${7}";
isSameSystemBrand =~ "${8}";
isSameSegment =~ "${9}";
isSameRateplan =~ "${10}";
isSameDiscountModel =~ "${11}";
isSameBillcycle =~ "${12}";
isBirthdayCall =~ "${13}";
isFriendsAndFamily =~ "${14}";
isHomeCell =~ "${15}";

RESULT:
edrString( DETAIL.USAGE_TYPE ) = "${16}"; 

IRL_UsageType.data

Each line in the IRL_UsageType.data file represents a different usage type mapping. Each position in a line corresponds to a variable (condition) in the IRL_UsgeType.irl file. The last position specifies the usage type code to apply if the mapping matches. This position corresponds to the result variable in the IRL_UsageType.irl file, which in the example above is “${16}";. Each position can have one of the following values:

• N = No

• Y = Yes

• .  = any value

The following examples show the mapping and usage type for the Friends and Family and Customer to Customer ERAs, respectively.

N;N;.;.;.;.;.;.;.;.;.;.;.;Y;.;FNF

N;N;.;Y;.;.;.;.;.;.;.;.;.;.;.;CTC

Using the configuration examples above:

• If an EDR is not roaming or international (N in positions 1 and 2) and uses the Friends and Family ERA (Y in position 14), the usage type FNF is assigned.

  This mapping is associated with these conditions in the IRL_UsageType.irl file:

  isRoaming =~ "${1}";
  isInternational =~ "${2}";
  isFriendsAndFamily =~ "${14}";
  

• If an EDR is not roaming or international (N in positions 1 and 2) and uses the Customer to Customer ERA (Y in position 4), the usage type CTC is assigned.

  This mapping is associated with these conditions in the IRL_UsageType.irl file:

  isRoaming =~ "${1}";
  isInternational =~ "${2}";
  isCustomerToCustomer =~ "${4}";

Configuring the IRL_UsageType iRule for Filter Sets

The IRL_UsageType iRule uses the following files in the pipeline_home/iScriptLib directory. There are samples of these files in that directory.

• ISC_UsageType.isc. This file contains the iScript code that determines whether an EDR qualifies for a usage type. This script reads EDR fields and sets a series of variables. It then assigns a usage type to the EDR based on a mapping of variables to usage type.

• IRL_UsageType.irl. This file contains a mapping to the contents of the IRL_UsageType.data file. For filter sets, this is a condition placeholder and a result placeholder.

• IRL_UsageType.data. This file contains one or more conditions and the usage type to be assigned. If the EDR contains attributes that match the conditions specified in this file, the corresponding usage type is set in the EDR.

Configuration example

Note:

This sample configuration shows how to configure the iRule for filter sets only. It does not show how to configure the iRule for ERAs, which is done differently. For information, see "Configuring the IRL_UsageType iRule for ERAs" and "Configuring the IRL_UsageType iRule for Both ERAs and Filter Sets".

ISC_UsageType.isc

For filter sets, all you need is the included ISC_UsageType Function.isc file, which is run when a condition is fulfilled.

IRL_UsageType.irl

The following example shows a placeholder condition that indicates the position in the IRL_UsageType.data file that contains the determination logic for applying the usage type. This example also shows a result placeholder for the usage type.

Note:

Do not include a string in the condition to represent the EDR field being checked. For filter sets, the fields are identified in the IRL_UsageType.data file.

CONDITION:
"${1}";

RESULT:
edrString( DETAIL.USAGE_TYPE ) = "${2}"; 

IRL_UsageType.data

Each line in the IRL_UsageType.data file represents a different usage type mapping. Each position in a line corresponds to the positions in the IRL_UsageType.irl file.

The following examples show rules for assigning a usage type to the EDR. For filter sets, the rule contains both the determination logic and the usage type to apply. You can use Boolean operators to define complex rules.

isSegmentContains("1234") and isSegmentContains("GOOD");A1

isSegmentContains("789") or isSegmentContains("OK");B2

Using the configuration examples above:

• If the CUST_SET_LIST field is set to 1234 and GOOD, the usage type A1 is assigned.

• If the CUST_SET_LIST field is set to 789 or OK, the usage type B2 is assigned.

Configuring the IRL_UsageType iRule for Both ERAs and Filter Sets

You can configure one set of IRL_UsageType iRule files for both ERA and filter set usage type mapping. For background information, see "Configuring the IRL_UsageType iRule for ERAs" and "Configuring the IRL_UsageType iRule for Filter Sets".

ISC_UsageType.isc

There is no special configuration in this file when you use it for both ERA and filter set usage type mapping. You need both the determination logic for ERAs and the included ISC_UsageType Function.isc file, which is run when a condition is fulfilled.

IRL_UsageType.irl

Combine both ERA variables and a placeholder condition for filter sets (${16}; in this example) in the IRL_UsageType.irl file. You need only one result entry.

CONDITION:
isRoaming =~ "${1}";
isInternational =~ "${2}";
isHomeRegion =~ "${3}";
isCustomerToCustomer =~ "${4}";
isSameClosedUserGroup =~ "${5}";
isSameCorporateAgreement =~ "${6}";
isSameCustomer =~ "${7}";
isSameSystemBrand =~ "${8}";
isSameSegment =~ "${9}";
isSameRateplan =~ "${10}";
isSameDiscountModel =~ "${11}";
isSameBillcycle =~ "${12}";
isBirthdayCall =~ "${13}";
isFriendsAndFamily =~ "${14}";
isHomeCell =~ "${15}";
${16};

RESULT:
edrString( DETAIL.USAGE_TYPE ) = "${17}"; 

IRL_UsageType.data

In the IRL_UsageType.data file, provide a separate line for each rule.

The following is a line to assign a usage type for a filter set. The condition is in position 16 and the result is in position 17.

Note:

Be sure to account for each condition in the IRL_UsageType.irl file.

.;.;.;.;.;.;.;.;.;.;.;.;.;.;.;isSegmentContains("1234") and isSegmentContains("GOOD");A1

The following is a line to assign a usage type for the Friends and Family ERA. The filter set position, 16, is set to any value (.).

N;N;.;.;.;.;.;.;.;.;.;.;.;Y;.;.;FNF

You can also combine ERA and filter set conditions in one rule. You can use this to apply an ERA usage type only to certain customers or to assign a filter set usage type to specific customers who also have an ERA:

N;N;.;.;.;.;.;.;.;.;.;.;.;Y;.;isSegmentContains("1234") and isSegmentContains("GOOD");C3

Configuring the FCT_IRule Module to Run the IRL_UsageType iRule

The IRL_UsageType iRule is run by the FCT_IRules module. You must run this instance of the FCT_IRules module after the FCT_Account module and before the FCT_USC_Map module.

Adding Customer Balance Impact Data to EDRs

Note:

Before adding balance impacts to an EDR, you must configure internal service codes. See "About Mapping Services".

Before rating an EDR, you must add the customer's balance impact data to the EDR. This data includes the following:

• The POID of the service-level item that receives the balance impact.

• The start and end times of the accounting cycle that applies to the event. This data assures that the charges are applied to the correct bill item.

To find the balance impact data, you configure the following modules:

• Use the FCT_Account module to look up the balance impact data and add it to the EDR.

• Use the DAT_AccountBatch module to supply data to the FCT_Account module.

Configuring the DAT_AccountBatch Module

The DAT_AccountBatch module stores all customer data from the BRM database. The FCT_Account and FCT_AccountRouter modules use the data stored by the DAT_AccountBatch module.

Note:

Because FCT_AccountRouter runs in a separate instance of Pipeline Manager, you configure separate instances of the DAT_AccountBatch module for the FCT_Account and FCT_AccountRouter modules.

The DAT_AccountBatch module stores the following types of data:

• Dynamic data, such as login names, charge offers, accounts, and services. This data is updated by the DAT_Listener module.

• Maintenance data, such as charge offers, packages, and bundles. Maintenance data is not updated constantly. Instead, it is updated only when all data is reloaded into the database.

To configure the DAT_AccountBatch module, see the following sections:

• Specifying Not to Load Closed Accounts

• Specifying Whether to Load All Account Data

• Specifying How Much Account Data to Retrieve on Startup

• Configuring Charge Offer Validity Checking

• Configuring Account Charge Offer Validity Checking for Backdated Events

Specifying Not to Load Closed Accounts

When you start Pipeline Manager, DAT_AccountBatch loads all accounts into memory. This can affect start-up performance when there are a great number of accounts. To improve Pipeline Manager start-up performance, you can reduce the number of accounts loaded into memory by specifying not to load closed accounts.

To not load closed accounts, you set the ClosedAccountDelay registry entry in the DAT_AccountBatch registry. Specify the number of days before the current date for which closed accounts are not loaded:

ClosedAccountDelay = number_of_days

For example, if the system time is 11:00 a.m. on June 25 and the number of days is 10, accounts that were closed before 11:00 a.m. on June 15 are not loaded into memory.

The ClosedAccountDelay registry entry applies only to closed accounts. Accounts that are inactive, and open accounts with inactive services, are still loaded into memory.

If delayed EDRs arrive in the pipeline for closed accounts that were not loaded into memory, those EDRs are rejected and not rated.

The ClosedAccountDelay registry entry uses only the system time, not the virtual time. If you set the virtual time and restart the pipeline, the virtual time is not considered when loading closed accounts.

For example, on June 20 you set the virtual time to June 5 and create an account. You then change the virtual time to June 9, close the account, and set ClosedAccountDelay to 10 days. When you restart the pipeline, the account is not loaded because it was closed more than 10 days before the system time (June 20), even though the current virtual time is June 9. EDRs that arrive for that account are rejected.

Specifying Whether to Load All Account Data

Use the DAT_AccountBatch module InitialLoading registry entry to specify whether the initial loading of service and account data is performed. If the data is not loaded, loading occurs while processing. Login objects are always loaded.

The default is True. Setting this entry to False enables the system to start faster, but processing might be slower.

Specifying How Much Account Data to Retrieve on Startup

Use the DAT_AccountBatch module RowFetchSize registry entry to specify the number of rows of data to retrieve from the BRM database. The default is 1000.

The value you enter is used only during the initialization of DAT_AccountBatch to improve performance. After the DAT_AccountBatch startup is completed, RowFetchSize automatically resets itself to a more appropriate value of 50 to conserve memory.

Configuring Charge Offer Validity Checking

You can use the DAT_Account module UseProductCreatedTime registry entry to configure how charge offer validity is checked:

• If you enable this entry, the charge offer created time is not considered when establishing charge offer validity. Only the start and end times are considered, so updates to charge offers are valid immediately.

• If you disable this entry, the module checks the created time and the start and end time of a charge offer when establishing the charge offer's validity. In some situations this procedure can lead to unexpected results. The created time (PIN_FLD_CREATED_T) is system-generated whenever the charge offer is modified. If the charge offer is modified after its start time (PIN_FLD_START_T), there can be a short period when the charge offer is invalid because its created time is later than the start time.

Configuring Account Charge Offer Validity Checking for Backdated Events

You can use the DAT_Account module UseLatestProductAndDiscount registry entry to configure validity checking for account charge offers and discount offers.

• If you enable this entry, when rating EDRs, DAT_AccountBatch retrieves account charge offer and discount offer information based only on their start and end dates.

• If you disable this entry, DAT_AccountBatch retrieves account charge offer and discount offer information based on their creation dates.

When charge offer and discount offer information is retrieved during EDR rating, pipeline modules validate the account charge offers and discount offers by using the account creation date. This date is the time that the charge offer and discount offer are purchased (the EFFECTIVE_T time in the AU_ACCOUNT_T audit table). If the charge offer's validity start date is earlier than the actual purchase date, which can occur when purchase events are delayed, usage events might be incorrectly rated.

For example, an account is created on January 1. On January 20, the customer purchases a discount offer with a validity period that starts on January 5. On January 25, a delayed event that is dated January 10 arrives for rating. The discount module does not apply the discount because it uses the purchase date of January 20 instead of the discount's start date of January 5. Only events dated on or after January 20 are discounted. Figure 13-1 shows a timeline for this example.

Figure 13-1 Charge Offer Validity for Backdated Events Example

Description of "Figure 13-1 Charge Offer Validity for Backdated Events Example"

If you set the UseLatestProductAndDiscount entry in the DAT_AccountBatch registry, account charge offer and discount audit information is not retrieved. If you want delayed events to use the account charge offer and discount offer that was valid at the time the usage occurred, do not set this entry.

Getting Information about Loading Accounts

You can use DAT_AccountBatch semaphore commands to get data about the accounts loaded into the DAT_AccountBatch module.

• PrintData - Reports the account data for all accounts.

  The data is written to the specified file. If you do not specify a file, it is written to stdout.

• PrintDataLogin - Reports the account data for a single account identified by the BRM login ID (usually the phone number).

  The data is written to a file named LoginID.lst.

• PrintDataSamples - Reports the account data for a specified number of accounts, chosen randomly.

  The data is written to a file named Value.lst. For example, if you enter 15, the file is named 15.lst.

  If no value is provided, the module prints data for 10 accounts to stdout.

Configuring the FCT_Account Module

To find the balance impact data:

1. The FCT_Account module looks for the following data in the EDR:

   • The internal service code that indicates which data can be used to identify the account that generated the EDR. For example, if the internal service code is a telephony service, the identifying data is the A number. A different service might use the IMSI as the identifier.

     You identify which data to use by using Pricing Center or PCC. See "Specifying Which Data Is Used for Identifying Accounts". Depending on the service, the module searches for either the login from a service object or an alias from a service object. An alias is typically a phone number or IMSI.

     In rare cases, one customer's MSISDN can be the same as another customer's IMSI. You can configure account ID prefixes to use for handling duplicate telephone numbers. See "Configuring Account ID Prefixes".

   • The timestamp for the EDR. The timestamp is important because telephone numbers can be used by different accounts at different times.

2. The FCT_Account module uses the DAT_AccountBatch module to look up the account.

   Note:

   • If the A customer is not found, the EDR is rejected. If the B customer is missing, no error is generated.

   • Because phone numbers can be recycled, the search is made on data from BRM audit objects.

   • Accounts are loaded based on the service that is being rated by the pipeline. If an account does not own the service that the pipeline rates, it is not loaded.

3. The DAT_AccountBatch module returns the balance impact data.

4. The FCT_Account module inserts the customer data into the EDR.

Specifying Which Data Is Used for Identifying Accounts

Different services require different ways to look up accounts. For example, to look up a telephone account, you can use the A number to find the originating account and the B number to find the account that was called.

To specify which data to use for looking up an account, you use Pricing Center or PCC to map the service to the type of data. The data is stored in the IFW_ALIAS_MAP table.

You can set up multiple mappings to support different services (for example, specify different mappings for each pipeline).

Note:

This data is used by both the FCT_Account module and the FCT_AccountRouter module.

Use the following data to specify how to identify accounts:

• The EDR container description that includes the field to use for identifying the account.

• The account reference. You must use one of the following:

  • Use Account_CustA for the A number.

  • Use Account_CustB for the B number.

• The internal service code (for example, TEL or DATA).

• The type (for example Internal or Plugin).

Configuring Account ID Prefixes

In some cases, the data used for identifying an account is not unique; for example, the MSISDN of one customer might have the same value as the IMSI of another customer. To avoid any conflicts, you can specify a prefix for the identifying data. This prefix data is stored in the IFW_REF_MAP database table.

You can specify a prefix based on the service type and event type, as shown in Table 13-3. In this case, the number is prefixed with either msisdn or imsi.

Table 13-3 Prefix Configurations

Service	Event	Prefix	Example of Result
/service/telco/gsm/telephony	/event/delayed/session/gprs	msisdn	msisdn00491721234567
/service/ip/gprs	/event/delayed/session/telco/gsm	imsi	imsi00491721234567

To set up prefixes:

1. Customize the PCM_OP_NUM_POL_DEVICE_ASSOCIATE and PCM_OP_SIM_POL_DEVICE_ASSOCIATE policy opcodes to add a prefix to the MSISDN or IMSI.

2. In the Pipeline Manager IFW_REF_MAP object, use the IFW_REF_MAP.REF_COL attribute to specify the prefix, for example, msisdn.

Specifying Which Noncurrency Sub-Balances to Load on Startup

The DAT_BalanceBatch module uses the noncurrency balance element validity to select the noncurrency sub-balances to load from the BRM database into pipeline memory. For example, if the Free Minutes balance element validity is 30 days, at Pipeline Manager startup, DAT_BalanceBatch selects all Free Minutes sub-balances that were valid for the last 30 days.

You configure the noncurrency balance element validity in the balance element configuration file (pin_beid). If the noncurrency balance element validity is not configured, DAT_BalanceBatch selects the sub-balances that were valid for 366 days by default

Note:

When you set the noncurrency balance element validity, the sub-balances that do not fall within the validity range are not loaded into pipeline memory and therefore are not available for rating or rerating of call details records (CDRs). To make available the sub-balances that are required for rating and rerating, set the balance element validity to an appropriate setting. For instance, if the CDRs are older than 366 days, you should set the validity greater than 366 days to ensure that all the sub-balances that are required are loaded and available for rating or rerating the CDRs. See "Configuring the Noncurrency Balance Element Validity".

If your business requires, you can configure DAT_BalanceBatch to load all the noncurrency sub-balances available in the BRM database. To load all the noncurrency sub-balances, use the SelectiveSubBalLoad entry in DAT_BalanceBatch registry. When this entry is set to False, DAT_BalanceBatch loads all noncurrency sub-balances, including the sub-balances that are expired, into pipeline memory.

Note:

When the BRM database contains a large number of noncurrency sub-balances, loading all sub-balances leads to increased Pipeline Manager startup times.

Configuring the Noncurrency Balance Element Validity

To configure the validity of a noncurrency balance element:

1. Edit the pin_beid file in BRM_home/sys/data/pricing/example.

   Follow the instructions in the pin_beid file.

   Note:

   If you are using an existing pin_beid file, you must manually add the Validity_in_days field to the syntax and set the balance element validity for the noncurrency balance element. In this example, the balance element validity for balance element 1000010 is set to 30 days.

   #beid r_mode round tol_min tol_max tol_pct beid_str_code symbol event stage con_rule_id apply_mode Name Validity_in_days
   #
   1000010 0 1 0.000000 0.000000 0.000000 MIN Min * 0 0 1 Free Domestic Minutes 30

   Note:

   The load_pin_beid utility overwrites the existing balance elements. If you are updating balance elements, you cannot load new balance elements only. You must load complete sets of balance elements each time you run the load_pin_beid utility.

2. Save and close the pin_beid file.

3. Run the following command:

   load_pin_beid pin_beid

   If you do not run the utility from the directory in which the pin_beid file is located, you must include the complete path to the file. For example:

   load_pin_beid BRM_home/sys/data/pricing/example/pin_beid 

   Tip:

   If you copy the pin_beid file to the directory from which you run the load_pin_beid utility, you do not have to specify the path or file name. The file must be named pin_beid.

4. Stop and restart the Connection Manager (CM).

   To verify that the noncurrency balance elements were loaded, you can display the /config/beid object by using Object Browser, or use the robj command with the testnap utility.

5. Start Pipeline Manager.

   At Pipeline Manager startup, DAT_BalanceBatch uses the noncurrency balance element validity in the /config/beid object to select the noncurrency sub-balances to load into pipeline memory.

Modifying and Loading the EDR Container Description

By default, BRM supports the following EDR container description:

• containerDesc.dsc: The rating EDR container description. Defines the format into which CDRs are converted so that they can be processed for rating by a pipeline input module.

The EDR container description is in the pipeline_home/formatDesc/Portal directory.

If the CDR requests you process include information that has no corresponding fields in the appropriate default EDR container description, you must modify the description to accommodate the custom data. See "Modifying EDR Container Descriptions".

After editing the rating EDR container description, you must load it into the appropriate Pipeline Manager database. See "Loading EDR Container Descriptions".

Modifying EDR Container Descriptions

If the CDR requests you process include information that has no corresponding fields in the default EDR container description, you must modify the description to accommodate the custom data.

The rating EDR container description (containerDesc.dsc) text file is located in pipeline_home/formatDesc/Portal.

EDR Container Description Format

An EDR container description has the following format:

ComplexDataType 
{ 
  String             StringVar;  //description 
  Integer            IntegerVar; 
  Date               DateVar; 
  Decimal            DecimalVar; 
  ComplexDataType_2  complexVar; 
} 
ComplexDataType_2 
{ 
  String             var1; 
  Decimal            var2; 
} 

The following example shows how to format an EDR container description file:

// Comments 
DETAIL // comment 
{ 
String A_Number; // Comment will be filled into the ifw_edrc_field.description 
Date STARTDATE; 
Decimal duration; 
CUSTOMER CUST_A; // New complex type must be defined later on 
CUSTOMER CUST_B; 
} 
HEADER 
{ 
// comment 
String name; 
Integer count; 
} 
CUSTOMER 
{ 
String account; 
String account_no; 
Purchased_Product PRODUCT; 
} 
Purchased_Product 
{ 
String name; 
Integer type; 
} 

Note the following syntax and grammar rules:

• The file is case-sensitive.

• Real data types are the following:

  • String

  • Integer

  • Date

  • Decimal

  • Block (for example, DETAIL.CUST_A)

• The parsing is done in one step. Therefore, embedded complex data types must be defined later in the file.

• The name of each complex data type must be written in one line.

• The complex data type area must begin with a left brace ( { ) and end with a right brace ( } ). Each brace must be in its own line.

• Each data type variable pair must be written in one line. The line must end with a semicolon ( ; ).

• Comments must begin with double slashes ( // ) and are valid until the end of the line.

• Comments following a real data type line are copied to the IFW_EDRC_FIELD.DESCRIPTION field.

Loading EDR Container Descriptions

After editing the rating EDR container description, you must load it into the Pipeline Manager database.

You use the containerDescLoader.pl utility to load an EDR container description into a database.

EDR container descriptions are stored in the following database tables:

• IFW_EDRC_DESC

• IFW_EDRC_FIELD

Note the following restrictions:

• The Container Description Loader utility can process only one EDR container description file at a time.

• You cannot update tables that already include data. You can initialize empty tables or delete the data from tables before adding new data. You cannot, however, delete existing data if there are references to it from elsewhere in the database.

Creating the EDR Load Utility Command File

The Container Description Loader utility uses a command file to load data into a database.

The syntax of the command file is as follows:

#comments 
ECHO print this on default output 
TYPE=Database type
SOURCE=Database source
USER=Database user
PASS=Database user password
INIT=TRUE | FALSE 
EDRC_DESC=Pipeline name as specified in the registry 
EDRC_DESC_FILE=Container description file 
EDRC_DESCRIPTION=Description of pipeline name 
RUN=Execute this command 

This is a sample command file with only the required entries:

DB=PR01|zaphod|zaphod 
EDRC_DESC_FILE= /FMD/Portal/containerDesc.dsc 
EDRC_DESC='MY_IFW' 
EDRC_DESCRIPTION='MY_IFW container description' 

This sample includes optional entries:

## 
## This is a sample command file for containerDescLoader.pl 
## 
## 
## DB (database connect) 
## database|user|password 
## 
DB=PR01|zaphod|zaphod 
# 
# initialization (deleting tables) 
# 
ECHO=################################### 
ECHO=# deleting of ifw_edrc_desc and ifw_edrc_field 
ECHO=################################### 
#INIT=FALSE 
INIT=TRUE 
# container description file 
EDRC_DESC_FILE= /FMD/Portal/containerDesc.dsc 
# pipeline name as specified in the registry 
# filled into IFW_EDRC_DESC.EDRC_DESC and IFW_EDRC_FIELD.EDRC_DESC 
EDRC_DESC='MY_IFW' 
# additional description 
# filled into IFW_EDRC_DESC.NAME 
EDRC_DESCRIPTION='MY_IFW container description' 
# optional command processing 
#RUN=prog 

Before Running the EDR Load Utility

Before running the Container Description Loader utility, do the following:

• Ensure that the following components are installed:

  • Perl 5.004 or higher

  • CPAN generic database interfaces

  • oraperl Perl module

• If necessary, create the following database tables:

  • IFW_EDRC_DESC

  • IFW_EDRC_FIELD

• If necessary, create the following sequence:

  • IFW_SEQ_FIELD_ID

• Use the IFW_PERL_LIB variable to find the required Perl modules.

Starting the EDR Load Utility

To start the Container Description Loader utility:

1. Go to the TLS_ContainerDescLoader directory.

2. Enter the following command:

   containerDescLoader.pl [-c command_file].

Dropping or Upgrading Incomplete Calls after Changing the EDR Container Description

The FCT_CallAssembling module stores any incomplete call records while a pipeline is running. When you stop the pipeline and change its container description, these incomplete call records are then automatically in the wrong format for the pipeline to process. This section describes your two choices for processing these call records:

• Discard them. This is the fastest way of dealing with the problem, but you lose the revenue they represent. You can however, use these EDRs for auditing purposes. For the procedure, see "Discarding Incomplete Calls after Changing the EDR Container Description".

• Upgrade them to the new container description. You use the tools provided to create a data upgrade pipeline that reformats the EDRs into the new container description format. For the procedure, see "Upgrading Incomplete Calls to the New Container Description".

These sections apply to all pipelines using FCT_CallAssembling to assemble CDRs into EDRs for the pipeline to process.

Discarding Incomplete Calls after Changing the EDR Container Description

This section explains the steps necessary to delete your partially-assembled call records during the process of changing the EDR container description.

You use the UpgradeFlushLimit semaphore registry entry to FCT_CallAssembling to flush and discard any incomplete calls stored in a pipeline during an EDR container description change.

You then use the EmitPartialEDROnUpgrade startup registry entry to specify what happens to the EDRs flushed by the UpgradeFlushLimit semaphore:

• If the EmitPartialEDROnUpgrade registry entry is False, the EDRs are silently dropped and are never processed by the pipeline.

• If the EmitPartialEDROnUpgrade registry entry is True, partial EDRs are processed by the pipeline but are not rated. You can use these records for revenue assurance purposes, but they should be discarded to avoid recycling.

EDR Data Available for Auditing

By default, all flushed EDRs will contain the following data fields:

• CHAIN_REFERENCE

• LONG_DURATION_INDICATOR (set to P)

• NUMBER_OF_CDRS

• CHARGING_START_TIMESTAMP

• CHARGING_END_TIMESTAMP

• DURATION

The following additional fields will also be included if the FCT_CallAssembling module has AssembleVolume set to True:

• VOLUME_SENT

• VOLUME_RECEIVED

• NUMBER_OF_UNITS

• RETAIL_CHARGED_AMOUNT_VALUE

• WHOLESALE_CHARGED_AMOUNT_VALUE

All EDR fields listed in the AssembledEDR registry entry are included if the L segment has been received.

Upgrading Incomplete Calls to the New Container Description

This section explains the steps necessary to update your partially-assembled call records to a new EDR container description. These tasks are necessary to correctly process any calls that are partially assembled at the time you shut down a pipeline to make the EDR container description changes.

Note:

The tasks in this section apply only to BRM implementations that use FCT_CallAssembling. If you use an external mechanism to assemble wireless records, the instructions in "Modifying and Loading the EDR Container Description" are all you need to modify your EDR container description.

To correctly rate the incomplete calls with your new EDR container description, you must first update the data file maintained by FCT_CallAssembling. The following procedure explains how to do this by running the EDRs through two miniature pipelines that you will create. After this conversion, you can process these calls through the pipeline set up to process call records using the new container description file. Before you run the pipelines, you will also create new input and output mapping and grammar files and a new stream file.

Figure 13-2 shows the process of upgrading stored EDRs to a new EDR container description.

Figure 13-2 Incomplete Call Description Update Process

Description of "Figure 13-2 Incomplete Call Description Update Process"

Note:

Using the RestoreEDRs and UpgradeEDRs modes, FCT_CallAssembling does not assemble calls. Instead, it only migrates them from one format to another.

Follow these steps to update EDRs being stored by FCT_CallAssembling to your new EDR format. This procedure assumes that you have already created your new container description file. For details see "Modifying EDR Container Descriptions".

Run this entire procedure for each EDR container being changed.

Note:

If you are upgrading multiple pipelines to the new container description, you only need to create one set of data upgrade pipelines. You can use them to upgrade all FCT_CallAssembling pipelines getting the new container description.

1. Run the pin_container_to_stream_format utility on your old EDR container description file.

   For example:

   pin_container_to_stream_format -c oldcontainer.dsc -g OLD_ -m OLD_ -s OLD_
   

   This creates the stream, input and output grammar, and input and output mapping files that you will use to convert the partially assembled EDRs.

2. (Optional) Make any changes to the data fields in the new input grammar file to match your new EDR container description. The new container description file will have automatically supplied any necessary field additions. Edit the grammar file to specify any other changes to existing fields.

3. Create data upgrade pipeline 1. This pipeline will have only the following modules:

   • INP_GenericStream using your old input mapping file (actually any input mapping file can be used here).

   • FCT_CallAssembling. Set Mode=RestoreEDRs and set the EdrFactory description entry to your old container description file.

   • OUT_GenericStream using the output mapping created by pin_container_to_stream_format in Step 1.

4. Create data upgrade pipeline 2. This pipeline will have only the following modules:

   • INP_GenericStream using the input mapping file created by pin_container_to_stream_format in Step 1 (modified as needed).

   • FCT_CallAssembling. Set Mode=UpGradeEDRs and set the EdrFactory description entry to your new container description file created in Step 1.

   • OUT_DevNull (removes the single CDR file you send in to initiate the pipelines).

5. Use a semaphore to stop the rating pipeline that is receiving the EDR container change. Wait for it to stop completely.

6. Back up the following files used by FCT_CallAssembling in your rating pipeline:

   • The most recent .dat file

   • All .EDR files

   • The most recent .INDEX file

7. Copy the most recent .dat file used by FCT_CallAssembling in your rating pipeline to the data directory used by FCT_CallAssembling in data upgrade pipeline 1 and data upgrade pipeline 2.

8. Copy the .EDR file used by FCT_CallAssembling from your rating pipeline to the EDR directory used by FCT_CallAssembling in data upgrade pipeline 1.

9. Copy the most recent .INDEX file used by FCT_CallAssembling in your rating pipeline to the index directory used by FCT_CallAssembling in data upgrade pipeline 1.

10. Use a semaphore to start the data upgrade pipelines.

11. Put one disposable CDR file in the input directory for data migration pipeline 1 to trigger the data upgrade. This file need only contain a single CDR, but it must use your old EDR container description format.

    Note:

    This CDR is needed only to start EDR processing; it will get dropped during processing.

12. Ensure that data upgrade pipeline processes have finished. The time required for these pipelines to update all EDRs varies with the number EDRs being updated.

13. Use a semaphore to stop the data upgrade pipelines.

14. Move the .dat and .EDR files from the data upgrade pipeline 2 output directory to the input directory of the FCT_CallAssembling pipeline receiving the EDR container change.

15. Install the new EDR container description in your rating pipeline, and start the pipeline.

This completes the process of upgrading all EDRs stored in FCT_CallAssembling while upgrading your EDR container description. These incomplete calls are processed normally.

About Serviceless Accounts as Charge Sharing Owners

Charge sharing group owners can be accounts that have no services. This enables you to bypass purchasing specific services for corporate accounts that are used exclusively to pool employee charges. For example, you can create a corporate account that assumes telephone, email, and IP charges for all employees in the marketing group. But, you do not have to purchase GSM, email, or IP services for that corporate account. If you set up a serviceless account as a charge sharing group owner, BRM applies the member charges to that account's default balance group.

Pipeline Manager uses the create, modify, and delete sharing group events to determine the owner of the sharing group. If the owner is an account without services, the PIN_FLD_SERVICE_OBJ value is NULL. If the owner is a service, the PIN_FLD_SERVICE_OBJ value is the POID of the service.

To create a charge sharing owner that is a serviceless account, perform the following:

1. Enable Pipeline Manager to accept serviceless accounts by setting the DAT_AccountBatch LoadAccountForSharingOnly registry entry to True. This prevents the pipeline from rejecting serviceless accounts if they are owners of balance element sharing groups. By default, this entry is set to False.

2. Create a serviceless account. First create a package that has no bundles. Then, purchase the package when you create the account. When you create a charge sharing group for this account, the result is an account-level charge sharing group not associated with any specific services.

Mapping Subscription Services in the Pipeline Manager Database

To rate subscription services in a pipeline, the data that defines the subscription service object must be mapped in the Pipeline Manager database. Sample mapping is provided by BRM for some service objects. However, if you set up a service object for the subscription service that is not already configured in the Pipeline Manager database, you must map that service to the data that defines it.

Use Pricing Center or PCC to map the subscription service in the following Pipeline Manager database tables:

• IFW_SERVICE specifies the pipeline rating service code to BRM rating service code mapping; for example, map GSM to /service/telco/gsm.

• IFW_SERVICE_MAP specifies the external data used to determine the internal service code. You define the mapping when you set up service code mapping.

• IFW_REF_MAP specifies the service-type-to-event-type mapping so that services are associated with usage events. This database table also specifies the prefix for the data that identifies an account; for example, MSISDN or IMSI.

  Note:

  Be sure to map a corresponding delayed event type to your subscription service object. For example, if you map to the usage event type /event/session/telco/gsm, also map to /event/delayed/session/telco/gsm. The delayed event type is used by Rated Event (RE) Loader when loading the rated events into the BRM database.

  If the delayed event type does not exist in the BRM database, you must create one. S

• IFW_ALIAS_MAP specifies which data to use for looking up an account in order to get the parameters for rating usage. You define the alias mapping when you set up EDR container fields.

  To define the alias mapping by using Pricing Center or PCC:

  1. From the Pipeline Setup Toolbox, select EDR - EDR Container Description.

  2. In the EDR Container Description dialog box, select the ALL_RATE sample container description and click Edit.

  3. Click the Alias Map tab and enter the alias data information for the subscription service.

Setting Up Batch Rating to Assign Items Based on Event Attributes

To set up Pipeline Manager to assign item tags to events based on event attributes:

1. Configure the following Pipeline Manager modules:

   • DAT_ItemAssign

   • FCT_ItemAssign

   • FCT_BillingRecord

2. Create a custom iScript that assigns item tags based on event attributes.

3. Load the rated events into the BRM database to update account balances and to create or update bill items.

Create a custom iScript that assigns item tags based on event attributes and fills in the DETAIL.ITEM_TAG field in the EDR container.

To enable your custom iScript to run in a pipeline, you must add an entry for it in the wireless.reg registry file. Configure this iScript to run after FCT_Account and before FCT_BillingRecord.

Sample registry entry:

# iScript to populate DETAIL.ITEM_TAG
#
IScript
{
  ModuleName = FCT_IScript
  Module
  {
   Active      = TRUE
   Source      = File
   Scripts
   {
    ItemTag
    {
     #iScript file that you created
     FileName = ./ISC_ItemTag.isc
    }
   }
  }
} 
# end of iScript
  

Loading the Rated Events into the BRM Database

You use Rated Event (RE) Loader to load rated events into the BRM database. Before updating items in the database, RE Loader checks the updater flag in the RE Loader Infranet.properties file. If the flag value is 1, RE Loader creates in the database the new item objects that were added. By default, the flag is set to 1.

How Batch Rating Assigns Custom Bill Items

BRM batch rating uses the FCT_ItemAssign pipeline module to assign items based on event and service combinations and uses custom iScripts to assign items based on event attributes.

To assign items to events, Pipeline Manager performs these tasks:

1. During initialization, the DAT_ItemAssign module loads the specified /config/item_types object into memory and reserves a pool of POID IDs. If the information in the DAT_ItemAssign config object changes, you can use the DAT_itemAssign module's Reload semaphore to refresh the configuration changes.

2. Your custom iScript assigns an item tag based on event attributes to the DETAIL.ITEM_TAG EDR field.

3. FCT_ItemAssign calls DAT_ItemAssign with the item tag in the DETAIL.ITEM_TAG EDR field.

4. DAT_ItemAssign retrieves the item POID list from the DAT_AccountBatch module.

5. DAT_ItemAssign retrieves the item type for the given item tag from the config/item_types object in memory and searches the POID list for a matching item type.

6. If DAT_ItemAssign finds a matching POID, it returns that item POID (for example, 1 /item/new_york m m) to FCT_ItemAssign.

   If DAT_ItemAssign does not find a matching POID, it creates a new POID ID from the POID pool it reserved and returns the new POID ID to FCT_ItemAssign.

   When the DAT_ItemAssign module creates new items, it updates DAT_AccountBatch with the new items it created; for example, 1 /item/new_york m m.

   If the DETAIL.ITEM_TAG field is NULL, DAT_ItemAssign returns a default item POID from the item POID list.

7. The FCT_ItemAssign module assigns the item POID that it retrieves to the DETAIL.CUST_A.PRODUCT.SERVICE_USED_ITEM_POID EDR field for the product used for rating the event.

8. For sponsored usage events, the following occurs:

   1. The FCT_BillingRecord module queries the DAT_ItemAssign module for items when required.

   2. The DAT_ItemAssign module returns the pre-created items of type /item/sponsor to FCT_BillingRecord for sponsored events.

   3. When the DAT_ItemAssign module creates new items, it updates DAT_AccountBatch with the new items it created; for example, 1 /item/sponsor m m.

9. Pipeline Manager generates the rated events.

You use Rated Event (RE) Loader to load the rated events into the BRM database and to update the account balances and create or update bill items.

Figure 13-3 shows how items are assigned to events:

Figure 13-3 Assignment of Items to Events

Description of "Figure 13-3 Assignment of Items to Events"

How Batch Rating Assigns Custom Bill Items to Events for Balance Impacts

BRM batch rating uses the FCT_ItemAssign pipeline module to assign items based on event and service combinations and uses custom iScripts to assign items based on event attributes and balance impacts. The FCT_BillingRecord pipeline module converts impacts from charge offers (ChargePacket), discount offers (DiscountPacket), and taxes (TaxPacket) to balance impacts.

To assign custom bill items to events for balance impacts, Pipeline Manager performs the following tasks:

1. During initialization, the DAT_ItemAssign module loads the appropriate /config/item_types object into memory and reserves a pool of POID IDs. If the information in the DAT_ItemAssign config object changes, you can use the DAT_itemAssign module's Reload semaphore to refresh the configuration changes.

2. Your custom iScript does the following:

   1. Assigns an item tag based on event attributes to the DETAIL.ITEM_TAG EDR field.

   2. Changes the item POID for a specific balance impact in the event, using the following ChargePacket, DiscountPacket, and TaxPacket EDR tag container fields:

      • DETAIL.ASS.CBD.CP.ITEM_TAG

      • DETAIL.ASS.CBD.DP.ITEM_TAG

      • DETAIL.ASS.CBD.TP.ITEM_TAG

3. If the ChargePacket, DiscountPacket, and TaxPacket EDR container tag field values are NULL, FCT_ItemAssign calls DAT_ItemAssign with the item tag from the DETAIL.ITEM_TAG EDR field.

   If the ChargePacket, DiscountPacket, and TaxPacket EDR container tag field values are not NULL, FCT_ItemAssign calls DAT_ItemAssign with the item tag from the ChargePacket, DiscountPacket, and TaxPacket EDR container fields and the item tag from the DETAIL.ITEM_TAG EDR field.

4. DAT_ItemAssign retrieves the item POID list from the DAT_AccountBatch module.

5. DAT_ItemAssign retrieves the item type for the given item tag from the config/item_types object in memory and searches the POID list for a matching item type.

6. If DAT_ItemAssign finds a matching POID, it returns that item POID (for example, 1 /item/new_york m m) to FCT_ItemAssign.

   If DAT_ItemAssign does not find a matching POID, it creates a new POID ID from the POID pool it reserved and returns the new POID ID to FCT_ItemAssign.

   When DAT_ItemAssign creates new items, it updates DAT_AccountBatch with the new items it created; for example, 1 /item/new_york m m.

   If the DETAIL.ITEM_TAG field is NULL, DAT_ItemAssign returns a default item POID from the item POID list.

7. The FCT_ItemAssign module does the following:

   1. Assigns the item POID that it retrieves to the DETAIL.CUST_A.PRODUCT.SERVICE_USED_ITEM_POID EDR field for the charge offer used for rating the event.

   2. Assigns the item POID that it retrieves from ChargePacket, DiscountPacket, and TaxPacket EDR container tag fields respectively to:

      • DETAIL.ASS.CBD.CP.ITEM_POID

      • DETAIL.ASS.CBD.DP.ITEM_POID

      • DETAIL.ASS.CBD.TP.ITEM_POID

   Note:

   If no item tags are configured for ChargePacket, DiscountPacket, and TaxPacket, FCT_ItemAssign replaces the corresponding packet's item POID with the updated POID from DETAIL.CUST_A.PRODUCT.SERVICE_USED_ITEM_POID.

8. For sponsored usage events, the following occurs if the SplitSponsorItemByMember business parameter is enabled:

   1. Pipeline Manager receives input from the config_item_tags.xml and config_item_type.xml files to determine the sponsor item type.

   2. Assigns a type-only POID; for example, /item/sponsor/usage-1.

   3. The RE Loader assigns an appropriate sponsor item instance to the sponsor balance impacts.

9. Pipeline Manager generates the rated events.

You use RE Loader to load the rated events into the BRM database and to update the account balances and create or update bill items.

Creating a Batch Rating iScript for Balance Impacts

BRM batch rating uses custom iScripts to assign items based on event attributes.

Create a custom iScript that does the following:

1. Assigns an item tag based on event attributes to the DETAIL.ITEM_TAG EDR field.

2. Changes the item POID for a specific balance impact in an event, using the following fields in the EDR container:

   • DETAIL.ASS_CBD.CP.ITEM_TAG

   • DETAIL.ASS_CBD.DP.ITEM_TAG

   • DETAIL.ASS_CBD.TP.ITEM_TAG

To enable your custom iScript to run in a pipeline, you must add an entry for it in the wireless.reg registry file. Configure this iScript to run after FCT_Apply_Balance and before FCT_ItemAssign.

Verifying Item-Tag-to-Item-Type Mapping

You can generate a log file that contains the item-tag-to-item-type mapping information from the DAT_ItemAssign memory.

To generate a log file of the mapping:

1. Create a semaphore registry file with following entry:

   ifw.DataPool.ItemAssignDataModule.Module.PrintData=TagTypeMap.txt
     

2. Copy the file into the semaphore directory. The default directory for semaphore files is BRM_home/ifw/semaphore.

Pipeline Manager generates the TagTypeMap.txt file, which contains the tag and type mapping from the DAT_ItemAssign module memory.

For example, the file contains entries as follows:

Total number of Tag and Type Mapping entries: 3
-----------------------------------------------------------
Tag : Type
-----------------------------------------------------------
cycle_forward : /item/cycle_forward
misc : /item/misc
newyork: /item/newyork