Configuring Pipeline Manager to Retrieve Business Events

Configuring the DAT_Listener Module

Each instance of Pipeline Manager is connected to one database queue. You must configure each instance's DAT_Listener module to connect to its corresponding database queue by modifying the Pipeline Manager registry.

Configuring the Registry

Perform the following tasks for each instance of Pipeline Manager:

Open the registry file.
Add the following entries to the Listener section of the registry file:

Note:

The Listener section must be listed after the pipeline and BRM database connection sections. Otherwise, Pipeline Manager fails to start.
```
Listener 
{ 
  ModuleName = DAT_Listener 
  Module 
  { 
    InfranetConnection =             #mandatory 
    QueueName =                      #mandatory 
    QueueLibrary =                   #mandatory
    ConnectRetries =                 #optional
    RetryInterval =                  #optional 
    LogEvents =                      #optional 
  } 
} 
```
where:
- InfranetConnection points to the registry file section specifying how the Oracle DM connects to the database queue.
  
  For example, ifw.DataPool.LoginAccountSync. This entry is mandatory.
- QueueName specifies the queue name.
  
  For example, IFW_SYNC_QUEUE. This entry is mandatory.
- QueueLibrary specifies if the Listener should use Oracle queue libraries. Enter OracleQueue.
- ConnectRetries specifies the number of times the DAT_Listener module retries to connect to the database queue.
  
  This entry is optional. The default is 0.
- RetryInterval specifies the time, in seconds, between reconnection attempts.
  
  This entry is optional. The default is 5.
- LogEvents specifies whether the entire contents of each business event is copied to a log file.
  
  This entry is optional. The default is FALSE.
Save and close the file.

Configuring Interleaved Processing

You can control how many events are waiting to be processed simultaneously by configuring DAT_Listener to interleave call detail record (CDR) and business event processing.

Note:

The following entries are optional. If not present, Pipeline Manager processes CDRs and business events concurrently.

To interleave processing between CDR and business events:

Open the registry file.
Add the following entries to the Listener section of the registry file:
```
Listener 
{ 
   ModuleName = DAT_Listener 
   Module 
   { 
    #Add the following lines for interleaved processing:
    InterleavingReqd = true
    MaxNumEvents = 
    MinNumEvents = 
    CheckInterval = 
    EnableInterLeavingStatistics =  
    ProcessAllEvents = 
    MaxEventProcessTime = 
    MaxCDRProcessTime = 
   } 
} 
```
where:
- InterleavingReqd specifies whether interleaved processing is enabled.
  
  The default is False. When set to False or not specified, interleaved processing is not performed; CDRs and events are processed simultaneously.
- CheckInterval specifies (in seconds) how frequently DAT_Listener checks the number of events waiting in the queue (specified by MaxNumEvents and MinNumEvents) and the amount of processing time that has passed (specified by MaxCDRProcessTime and MaxEventProcessTime).
  
  The default is 60. If this entry is not present, the default interval is used.
  
  Note:
  
  This entry takes precedence over MaxNumEvents, MinNumEvents, MaxEventProcessTime, and MaxCDRProcessTime. If CheckInterval is set too high, DAT_Listener will not switch between CDR and event processing even if the thresholds have been reached. For example, if MaxEventProcessTime is set to 3600 seconds and CheckInterval is set to 7200 seconds, events are processed for 7200 seconds before the processing time is checked.
- MaxNumEvents specifies the maximum number of business events allowed in the queue.
  
  The default is 900. When the number of events in the queue reaches or exceeds this amount, DAT_Listener stops CDR processing and starts business event processing. When this entry is specified, MinNumEvents must also be specified.
- MinNumEvents specifies the minimum number of business events allowed in the queue.
  
  The default is 300. When the number of events in the queue reaches or drops below this amount, DAT_Listener stops business event processing and starts CDR processing. When this entry is specified, MaxNumEvents must also be specified.
- EnableInterLeavingStatistics specifies whether to log only interleaving statistical data.
  
  The default is False. By default, DAT_Listener logs all processing messages in the pipeline processing log (process.log). If this entry is set to True, only statistical data related to the rate of interleaved processing is logged. You can use this entry to monitor your event processing performance.
- ProcessAllEvents specifies whether to process all events in the queue when Pipeline Manager is started.
  
  A value of True processes all events in the queue before activating interleaved processing. A value of False activates interleaved processing at startup, and events are processed according to the interleaving settings.
  
  If set to True at startup, this entry is reset to False after processing all events. To use this feature, reset this entry to True each time you restart Pipeline Manager.
- MaxEventProcessTime specifies the maximum number of seconds that business events are processed.
  
  The default is 60. When Pipeline Manager has been processing business events for this amount of time, DAT_Listener stops business event processing and starts CDR processing regardless of how many business events are in the queue. When this entry is specified, MaxNumEvents, MinNumEvents, and MaxCDRProcessTime must also be specified.
- MaxCDRProcessTime specifies the maximum number of seconds that CDRs are processed.
  
  The default is 300. When Pipeline Manager has been processing CDRs for this amount of time, DAT_Listener stops CDR processing and starts business event processing regardless of how many CDRs are in the queue. When this entry is specified, MaxNumEvents, MinNumEvents, and MaxEventProcessTime must also be specified.
  
  Note:
  
  The default values for interleaved processing are also the minimum required values. If you specify a value less than the default for any entry, that value is ignored, and the default value is used.
  
  You can use some entries in a semaphore to update the processing thresholds. If these semaphores contain an error, the pipeline is deactivated, and you must reactivate it.
Save and close the file.

Switching to Business Event Processing When No CDRs Are Waiting

When there are no CDRs to process, DAT_Listener waits until either the CDR processing time threshold is reached or the maximum number of business events is reached before switching to business event processing. If this wait period is too long, you can shorten the CDR processing time using a semaphore to update the DAT_Listener registry. The new semaphore value becomes effective the next time DAT_Listener checks for the number of events and elapsed processing time. The CheckInterval registry entry determines this. For example, if you set CheckInterval to 180 seconds, the semaphore update becomes effective after 180 seconds.

Use one of the following semaphores to shorten the CDR processing time so that business events are processed sooner:

Shorten the CDR processing time by changing the MaxCDRProcessTime value:
```
ifw.DataPool.Listener.Module.MaxCDRProcessTime=new_value
```
Reduce the maximum number of business events by changing the MaxNumEvents value:
```
ifw.DataPool.Listener.Module.MaxNumEvents=new_value
```
If the number of business events waiting in the queue exceeds the new value, DAT_Listener immediately switches to business event processing when it checks the number of events.

Setting Up Service-Level Bill Items

To enable Pipeline Manager to choose the correct bill item for an event, you must configure BRM to pre-create service-level items.

To set up service-level bill items, run the load_config_item utilities to load the contents of the config_item_tags and config_item_types files into the BRM database.

Modifying Business Events before Sending Them to Pipeline Manager

You can modify the BRM events that make up a business event before the business event is sent to the Oracle DM for publishing to Pipeline Manager. You do this by customizing the synchronization policy opcode, PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT.

Note:

Customizing the policy opcode requires programming knowledge and should be performed only by a developer.

You should modify an event to filter out unneeded data, which can improve performance if you publish large quantities of events. You can also use a flag to specify how adjustments should be applied to the account balance, for example, to permit the account to have a negative balance.

To modify a business event before sending it to Pipeline Manager:

Ensure that all the BRM events that form the business event are associated with opcode 3626 (PCM_OP_IFW_SYNC_PUBLISH_EVENT) in your system's event notification list.
Use PCM_OP_IFW_SYNC_PUBLISH_EVENT to process the BRM events that make up the business event.

See "Processing BRM Events That Form Business Events".
Use the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode to customize the BRM events that make up the business event.

See "Modifying BRM Events That Form Business Events".

Processing BRM Events That Form Business Events

PCM_OP_IFW_SYNC_PUBLISH_EVENT passes BRM events that form business events to the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode for modification.

PCM_OP_IFW_SYNC_PUBLISH_EVENT is called by the event notification feature when an event associated with this opcode in your system's event notification list occurs.

By default, PCM_OP_IFW_SYNC_PUBLISH_EVENT does not modify events; it only passes them to the policy opcode.

If the BRM event is published in the business event, PCM_OP_IFW_SYNC_PUBLISH_EVENT returns one of two POIDs:

If the object passed in was an /event type object, the event POID is returned.
If the object passed in was not an /event type object, a POID of type /publish is returned.

If the BRM event is not published (for example, if you filter out the event based on your business logic), the input flist is returned.

Modifying BRM Events That Form Business Events

You can customize the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode to remove or enhance BRM events and event fields before they are assembled into business events and sent to Pipeline Manager. For example, you can customize this opcode to:

Filter out BRM events you want to exclude from published business events for various business or performance reasons.
Note:
- Do not filter out balance impact fields based on the balance element ID. If you do, remove fields needed by Pipeline Manager.
- Do not modify the code that prepares the login fields (the fm_ifw_sync_pol_prep_logins function). This code is required when a login is changed.
Modify the value of the PIN_FLD_FLAGS field that is added to PIN_FLD_BAL_IMPACT arrays. This field specifies how to apply adjustments. For example, you can permit a negative balance by specifying a value of 4. By permitting a negative balance, the negative amount will be deducted from the account balance with the next billing cycle.

You could use this method when a customer purchases a service that includes 60 free minutes per month and cancels the service before the end of the month. Suppose the customer has used all 60 minutes, but you prorate the free minutes. In that case, the amount of usage for the canceled period can be deducted with the next billing cycle (provided the customer has a positive balance at that time).

By default, the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode modifies the following BRM events listed in Table 49-1.

Table 49-1 BRM Events Modified by PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT

Event	Action
/event/billing/debit	Adds a PIN_FLD_FLAGS field to each PIN_FLD_BAL_IMPACT array. This field indicates how adjustments should be applied: 1 applies the entire adjustment to the current month. This flag is the default for cycle-forward events. 2 applies an adjustment over a period of months. Note: This flag value is not implemented. 4 permits a negative account balance. Use this flag to specify a negative balance for balance elements, such as when prorating free minutes. If this field is not set, any balance that results in a negative value is removed. To specify more than one option, sum the values. For example, to apply the entire adjustment to the current month (1) and allow a negative balance (4), set this flag to 5.
/event/billing/product/fee/cycle/*	Filters out these event types after the first occurrence. These events are generated when a charge offer is purchased and when billing is run. For charge offer purchases, Pipeline Manager must be notified to update the in-memory account data. However, Pipeline Manager performs the account balance update for billing and does not need this event passed in.
/event/billing/sub_bal_validity	Creates a PIN_FLD_SUB_BAL_IMPACTS array in the event. PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT populates this array with information from element 1 of the existing PIN_FLD_SUB_BAL_AUDIT array for the event. Element 1 stores the updated validity period and the balance element and balance group associated with the sub-balance. Adding PIN_FLD_SUB_BAL_IMPACTS with the new validity period enables the DAT_BalanceBatch module to update the rating basis dynamically.
/event/customer/login	Copies PIN_FLD_SERVICE_OBJ from the top level of the input flist into the new login field (element 1) in the PIN_FLD_LOGINS array. This ensures that Pipeline Manager knows which service is associated with the new login.

If the BRM event is published in the business event, the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode returns one of the following POIDs:

If the object passed in was an /event type, the event POID is returned.
If the object passed in was not an /event type object, a POID of type /publish is returned.

If the BRM event is not published (for example, if you filter out the event based on your business logic), the input flist is returned.

Synchronizing Balance Group Transfer Data with Pipeline Manager

If your system uses both real-time rating and batch rating, you must configure BRM to notify Pipeline Manager when:

A service transfers to a different balance group.
A balance group transfers to a different bill unit.

BRM notifies Pipeline Manager through the ServiceBalanceGroupTransfer business event.

To configure BRM to notify Pipeline Manager when a service transfers to a different balance group, configure it to publish the ServiceBalanceGroupTransfer business event to the AQ database queue.

When configuring synchronization:

Ensure the ServiceBalanceGroupTransfer business event is listed in your payload configuration file under the <PublisherDefs> section. This business event appears in the default payload configuration file (BRM_home/sys/eai_js/payloadconfig_ifw_sync.xml).
Ensure the event notification list maps the /event/notification/service_balgrp_transfer/data notification event to opcode 3626. This mapping appears in the default event notification file (BRM_home/sys/data/config/pin_notify_ifw_sync).
Add the ServiceBalanceGroupTransfer business event to your BRM_home/sys/dm_aq/aq_queuenames file if the file is configured to send specific business events.