7 Setting Up Pipeline-Triggered Billing

This chapter provides a conceptual overview and instructions on setting up Oracle Communications Billing and Revenue Management (BRM) pipeline-triggered billing.

Before reading this chapter, read the following:

About Billing
"About Pipeline Rating" in BRM Configuring Pipeline Rating and Discounting
About the Billing Utilities
"About Standard Recycling" in BRM Configuring Pipeline Rating and Discounting

About Pipeline-Triggered Billing

You use pipeline-triggered billing when event data records (EDRs) arrive for the next accounting cycle before the associated accounts have been billed. Pipeline Manager triggers billing for these accounts, enabling the new usage to be rated sooner and reducing the number of EDRs that might need suspending or rerating.

When customers use their services while their accounts are being billed, Pipeline Manager does not rate their usage until the accounts' billing is complete. The BRM billing process can sometimes take several hours. When there is account activity during the billing process, there is a greater possibility that call detail records (CDRs) will need recycling or rerating. When you use pipeline-triggered billing, the accounts are billed in a separate billing process, reducing the billing processing time.

When Pipeline Manager suspends EDRs because it is waiting for the account to be billed, those EDRs must later be recycled for rating. Each time an EDR is recycled, it is suspended until Pipeline Manager receives notification that the billing process for the account is complete.

Figure 7-1 shows how a CDR is repeatedly suspended for Account X until the account's billing is complete. In this example, the billing process takes almost three hours.

Figure 7-1 Suspension of CDR Rating During Billing

Description of ''Figure 7-1 Suspension of CDR Rating During Billing''

With pipeline-triggered billing, billing is triggered for Account X when the first new CDR arrives, as shown in Figure 7-2. The account is billed in a separate billing process, reducing the processing time. Pipeline Manager can then rate the recycled CDR and new CDRs that arrive for the next accounting cycle for that account:

Figure 7-2 Pipeline-Triggered Billing

Description of ''Figure 7-2 Pipeline-Triggered Billing''

Note:

Performance is affected by the number of accounts that need pipeline-triggered billing. If too many accounts are triggered for billing by Pipeline Manager, there is no performance advantage.

Pipeline-Triggered Billing Components

Pipeline-triggered billing comprises several components that work together to bill accounts:

Pipeline Manager modules flag and route EDRs for accounts that require billing. See "About the Pipeline-Triggered Billing Modules".
BRM recycling suspends EDRs flagged to trigger billing until the accounts are billed. The EDRs are periodically recycled. When the accounts are billed, the recycled EDRs can be rated and are no longer suspended. See "About Suspending Billing-Trigger EDRs".
Billing-trigger applications bill the triggered accounts. These applications include a billing batch handler (BillHandler) and the BRM billing utility. When the accounts are billed, BRM notifies Pipeline Manager that billing for the accounts is complete. See "About BillHandler".

Figure 7-3 shows the relationships among Pipeline Manager, BRM standard recycling, and the billing-trigger applications.

Figure 7-3 Pipeline Manager, Recycling and Billing Applications Relationship

Description of ''Figure 7-3 Pipeline Manager, Recycling and Billing Applications Relationship''

How Pipeline Manager Triggers Billing

The following steps describe the entire process of pipeline-triggered billing:

BRM runs billing when the accounting cycle ends.
An EDR enters a pipeline for processing.
The FCT_TriggerBill module checks if the EDR belongs to the next accounting cycle and if partial billing has not yet been triggered for the account. When both of these conditions are true, it sends the EDR to the billing-trigger output stream.
The FCT_Reject module sends the EDR to the suspense output stream.

For more information, see "About the Pipeline-Triggered Billing Modules".
When the EDR reaches the output modules, the data in the EDR takes two routes:

Suspend EDR:
1. The suspense output module suspends the EDR by sending it to Suspended Event (SE) Loader. SE Loader stores the EDR in the BRM database.
2. The pin_recycle utility retrieves the EDR from the BRM database and sends it back through the rating pipeline. The EDR begins the cycle again at step 2: If billing for the account is complete, the EDR is rated. If billing is not complete, the EDR is again suspended.
  
  For more information, see "About Suspending Billing-Trigger EDRs".
Trigger billing:
1. The pipeline billing-trigger output module creates a file containing the account and bill units associated with the EDR.
2. The billing-trigger applications retrieve the file and bill the account associated with the EDR.
  
  For more information, see "About BillHandler".
3. BRM uses the Account Synchronization Data Manager (DM) to notify Pipeline Manager that the account is billed.
  
  For more information about the account synchronization process, see "Installing and Configuring the Account Synchronization DM" in BRM Installation Guide.
4. When the recycled EDR is sent back through a rating pipeline (through the Suspend EDR route), the EDR is rated because the account has been billed.

About the Pipeline-Triggered Billing Modules

Pipeline Manager flags EDRs associated with accounts that require immediate billing and sends them to the appropriate output streams. Pipeline-triggered billing uses the following modules:

The FCT_TriggerBill module, which determines whether EDRs should trigger billing based on the accounting cycle date and billing state. To trigger billing, it sets a billing-trigger error code (Awaiting billing of account) in the EDRs. To flag the EDRs for recycling, it sets a billing-trigger recycle key value (Trigger_Billing).
The FCT_Reject module, which detects the billing-trigger error code and sends the EDR to the suspense output stream.
The billing-trigger output module, which creates a file containing the accounts and bill units for billing and sends the file to a separate directory.
The suspense output module, which adds the EDRs that trigger billing to an output file. The EDRs are loaded into the BRM database to be suspended and recycled.

Figure 7-4 shows the path that EDRs take when they are flagged to trigger billing:

Figure 7-4 EDR Path for Triggered Billing

Description of ''Figure 7-4 EDR Path for Triggered Billing''

About BillHandler

BillHandler bills the accounts whose EDRs are flagged to trigger billing. BillHandler is used with the following applications:

Batch Controller, which watches for billing-trigger files output by a pipeline. When a file is present, Batch Controller starts BillHandler.
The pin_bill_accts billing utility, which bills the accounts and bill units. BillHandler starts the billing utility.

Figure 7-5 shows the batch handler billing process:

Figure 7-5 Batch Handler Billing Process

Description of ''Figure 7-5 Batch Handler Billing Process''

Overview of the Immediate Billing Process

To bill accounts identified for immediate billing, the following actions are performed:

Batch Controller starts BillHandler when a file is present in the pipeline billing-trigger output directory.
BillHandler reads the accounts and bill units in the file and passes them to the pin_bill_accts billing utility to be billed.
The pin_bill_accts billing utility creates the bills and updates the account information in the BRM database.
When the accounts are billed, BRM notifies Pipeline Manager by sending a business event to the Account Synchronization DM.

For information about synchronizing account data, see "Installing and Configuring the Account Synchronization DM" in BRM Installation Guide.

Figure 7-6 shows an overview of the processes required to bill accounts that are identified for immediate billing:

Figure 7-6 Immediate Accounts Billing Process

Description of ''Figure 7-6 Immediate Accounts Billing Process''

About Suspending Billing-Trigger EDRs

EDRs that are flagged to trigger billing are not rated and must be periodically recycled until the accounts are billed. Pipeline-triggered billing uses BRM standard recycling to suspend and recycle these EDRs.

You perform the following actions to suspend and recycle EDRs:

When EDRs contain the Awaiting billing of account error code, the FCT_Reject module sends them to the suspense output stream.
SE Loader retrieves the EDRs from the output stream and stores them in the BRM database. For more information, see "About Standard Recycling" in BRM Configuring Pipeline Rating and Discounting.
The pin_recycle utility retrieves the EDRs from the BRM database and sends them back through the rating pipeline. To continuously recycle any waiting EDRs, schedule the utility to run periodically. For more information, see "Setting Up pin_recycle to Run Periodically" in BRM Configuring Pipeline Rating and Discounting.

EDRs are suspended each time they are recycled until the accounts are billed. After the accounts are billed, the EDRs are rated and are no longer sent to the suspense output stream.

Figure 7-7 shows an overview of the processes required to suspend and recycle EDRs flagged to triggered billing:

Figure 7-7 Suspension and Recycling of EDRs Flagged to Trigger Billing

Description of ''Figure 7-7 Suspension and Recycling of EDRs Flagged to Trigger Billing''

Configuring Pipeline-Triggered Billing

To configure pipeline-triggered billing:

Configure Pipeline Manager. See "Setting Up Pipeline Manager to Trigger Billing".
Configure Batch Controller. See "Setting Up the Billing Batch Applications".
Configure Pipeline Manager recycling. You can use either standard recycling or Suspense Manager with pipeline-triggered billing. For a comparison of these features, see "About the EDR Recycling Features" in BRM Configuring Pipeline Rating and Discounting.

Setting Up Pipeline Manager to Trigger Billing

To set up Pipeline Manager to trigger billing:

Configure the FCT_TriggerBill module. See "FCT_TriggerBill" in BRM Configuring Pipeline Rating and Discounting.

Use the TriggerBillCreateStream entry in the module registry to specify the billing-trigger output module.

Configure the billing-trigger output stream in the OUT_GenericStream module. See "Configuring EDR Output Processing" and "OUT_GenericStream" in BRM Configuring Pipeline Rating and Discounting.

The default output grammar file is TriggerBilling_OutGrammar.dsc.

The following is an example of the registry entries for the billing-trigger instance of the OUT_GenericStream and EXT_OutFileManager modules:

TriggerBillCreateOutput
{
   ModuleName = OUT_GenericStream
   ProcessType = RATING_PIPELINE
   EventType = /event/delayed/session/telco/gsm
   Module
   {
      Grammar = ./formatDesc/Formats/TriggerBill/TriggerBilling_OutGrammar.dsc
      DeleteEmptyStream = True
      OutputStream
      {
         ModuleName = EXT_OutFileManager
         Module
         {
            OutputPath            = ./data/TriggerBill
            OutputPrefix          = trigger_billing
            OutputSuffix          = .tb
            TempPrefix            = .
            TempDataPath          = ./data/TriggerBill
            TempDataPrefix        = trigger.billing.tmp.
            TempDataSuffix        = .data
            AppendSequenceNumber  = True
            Replace               = True
         }
      }
   }
}

Important:

To ensure output file integrity, specify a unique combination of OutputPath, OutputSuffix, and OutputPrefix values for each output stream defined in the registry.

Add the format and mapping files to the DataDescription registry. For information about the DataDescription registry, see "Configuring EDR Output Processing" in BRM Configuring Pipeline Rating and Discounting.
- The default StreamFormats file is TriggerBilling.dsc.
- The default OutputMapping file is TriggerBilling_OutMap.dsc.
The following is an example of the billing-trigger entries in the DataDescription registry:
```
DataDescription
{ 
   Standard 
   { 
   ModuleName = Standard 
   Module 
   {
   StreamFormats
   {
      TRIGGERBILL_CREATE_OUTPUT =./formatDesc/Formats/TriggerBill/TriggerBilling.dsc   
   }
   . . .
   OutputMapping
   {
      TRIGGERBILL_CREATE_OUTPUT =                            ./formatDesc/Formats/TriggerBill/TriggerBilling_OutMap.dsc
   }
   }
   }
}
```

Setting Up the Billing Batch Applications

To set up the billing batch applications for pipeline-triggered billing:

Configure batch controller to start BillHandler. See "Configuring Batch Controller to Start BillHandler".
Configure BillHandler. See "Configuring BillHandler".

Configuring Batch Controller to Start BillHandler

Use Batch Controller to start BillHandler. You configure Batch Controller to start BillHandler when it detects a file in the pipeline billing-trigger output directory.

To configure Batch Controller:

Open the BRM_Home/apps/batch_controller/Infranet.properties file, where BRM_Home is the directory in which BRM is installed.

Add the entries shown in Table 7-1 for BillHandler:

Table 7-1 BillHandler Entries

Entry	Description
batch.random.events	Specify the event identifier. For example: batch.random.events = Bill_Handler_file For pipeline-triggered billing, this event is the appearance of a billing-trigger file that is output by a pipeline.
event_name.name	Specify a description for the event identifier. For example: Bill_Handler_file.name = File passed to BillHandler
event_name.file.location	Specify the full path to the pipeline billing-trigger output directory. This is the directory where the billing-trigger output module deposits the file of accounts to be billed.
event_name.file.pattern	Specify the billing-trigger output file name. When Batch Controller detects a file with this name, it starts BillHandler. Tip: You can use an asterisk () to represent zero or more characters in the file name. No other wildcards are supported. For example: Bill_Handler_file.pattern = .out
event_name.handlers	Specify BillHandler identifier. For example: Bill_Handler_file.handlers = BillHandler
handler_name.name	Specify a description for the BillHandler identifier. For example: BillHandler.name = Bill Handler that executes pin_bill_accounts
handler_name.max.at.lowload.time handler_name.max.at.highload.time	Specify the number of BillHandler instances that can run concurrently during periods of low-load and high-load usage. Typical default settings are 6 at low load and 3 at high load.
handler_name.start.string	Specify the command that starts BillHandler. The default is BRM_Home/apps/pin_bill_handler/BillHandler.pl.

Save and close the file.

For more information, see "Controlling Batch Operations" in BRM System Administrator's Guide.

Configuring BillHandler

BillHandler retrieves the pipeline-triggered billing output file and sends the account and bill units to the billing utility. After the accounts and bill units are billed, BillHandler deposits the input file to a separate directory.

To configure BillHandler:

Open the BRM_Home/apps/pin_bill_handler/BillHandler_config.values file.

Edit the entries listed in Table 7-2:

Table 7-2 Configuration Values for BillHandler

Entry	Description
$FILETYPE	Specify the EDR file-name pattern. For example, .txt.bc. Note: The asterisk () represents zero or more characters in the file name. No other wildcards are supported. Batch Controller runs BillHandler for each file with a name that matches this pattern.
$HANDLER_DIR	Specify the full path to the directory containing BillHandler, log, input, output, and other files. The default is BRM_Home/apps/pin_bill_handler.
$pinBillActDir	Specify the full path to the directory containing the pin_bill_accts billing utility.
$STAGING	Specify the full path to the BillHandler input file location. Note: This is typically the same location specified for $HANDLER_DIR. You configure this location as the output directory.
$PROCESSING	Specify the full path to the directory from which the billing-trigger files are processed. The default is $pinBillActDir.

For information about other entries, see the BillHandler_config.values file.

Save and close the file.

For more information, see "Controlling Batch Operations" in BRM System Administrator's Guide.