39 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.

About Pipeline-Triggered Billing

When you use pipeline batch rating, if an account is currently in the process of being billed, incoming call records are suspended (not rated) for that account until its billing is complete. The number of accounts being billed affects the time it takes to complete the billing process. When you need accounts to be billed quickly so that their new usage can be rated, you can set up Pipeline Manager to trigger billing. This will reduce the number of call records that might need suspending. When Pipeline Manager triggers billing for an account, it is billed in a separate billing process.

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 39-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 39-1 Suspension of CDR Rating During Billing

Description of "Figure 39-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 39-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 39-2 Pipeline-Triggered Billing

Description of "Figure 39-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 39-3 shows the relationships among Pipeline Manager, BRM standard recycling, and the billing-trigger applications.

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

Description of "Figure 39-3 Pipeline Manager, Recycling and Billing Applications Relationship"

How Pipeline Manager Triggers Billing

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

1. BRM runs billing when the accounting cycle ends.

2. An EDR enters a pipeline for processing.

3. 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.

4. The FCT_Reject module sends the EDR to the suspense output stream.

   For more information, see "About the Pipeline-Triggered Billing Modules".

5. 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: 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.

   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 39-4 shows the path that EDRs take when they are flagged to trigger billing:

Figure 39-4 EDR Path for Triggered Billing

Description of "Figure 39-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 39-5 shows the batch handler billing process:

Figure 39-5 Batch Handler Billing Process

Description of "Figure 39-5 Batch Handler Billing Process"

Overview of the Immediate Billing Process

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

1. Batch Controller starts BillHandler when a file is present in the pipeline billing-trigger output directory.

2. BillHandler reads the accounts and bill units in the file and passes them to the pin_bill_accts billing utility to be billed.

3. The pin_bill_accts billing utility creates the bills and updates the account information in the BRM database.

4. When the accounts are billed, BRM notifies Pipeline Manager by sending a business event to the Account Synchronization DM.

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

Figure 39-6 Immediate Accounts Billing Process

Description of "Figure 39-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:

1. When EDRs contain the Awaiting billing of account error code, the FCT_Reject module sends them to the suspense output stream.

2. SE Loader retrieves the EDRs from the output stream and stores them in the BRM database.

3. 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.

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 39-7 shows an overview of the processes required to suspend and recycle EDRs flagged to triggered billing:

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

Description of "Figure 39-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.

Setting Up Pipeline Manager to Trigger Billing

To set up Pipeline Manager to trigger billing:

1. Configure the FCT_TriggerBill module.

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

2. Configure the billing-trigger output stream in the OUT_GenericStream module.

   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
            }
         }
      }
   } 

   Note:

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

3. Add the format and mapping files to the DataDescription registry.

   • 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:

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

2. Add the entries shown in Table 39-1 for BillHandler:

   Table 39-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.

3. Save and close the file.

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:

1. Open the BRM_home/apps/pin_bill_handler/BillHandler_config.values file.

2. Edit the entries listed in Table 39-2:

   Table 39-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.

3. Save and close the file.

Running the pin_bill_accts Utility

When Batch Handler runs the pin_bill_accts utility, it uses the -from_file parameter. This parameter specifies that the accounts to bill will be read from a file, and the associated file name. The input file is passed to the pin_bill_accts utility by the BillHandler billing batch handler to trigger billing for the accounts specified in the file.