46 Synchronizing Account Data between BRM and Pipeline Manager

You can set up your Oracle Communications Billing and Revenue Management (BRM) system to synchronize account data between the BRM database and Pipeline Manager.

Topics in this document:

• About Account Synchronization with Pipeline Manager

• About Controlling the Business Event Backlog

About Account Synchronization with Pipeline Manager

Account synchronization enables Pipeline Manager to act on events that occur in BRM based on the event type. For example, when charge offers are purchased or an account's status is changed, the account information is updated in the Pipeline Manager database so that service usage events can be rated properly. The Oracle Data Manager (DM) sends the updated information to an Oracle Advanced Queuing (AQ) database queue, where Pipeline Manager retrieves it.

You set up the following Pipeline Manager modules to retrieve events:

• DAT_Listener: All events are retrieved by this module first. This module passes the events to the other modules set up to receive them.

• DAT_AccountBatch: This module receives account update information to ensure that Pipeline Manager uses the most current account information when rating events.

• DAT_BalanceBatch: This module receives balance update information to ensure that Pipeline Manager uses the most current balance information when rating events.

• DAT_Discount: This module receives discount balance update information to ensure that Pipeline Manager uses the most current discount balance configuration when rating events.

To configure your system to synchronize account data between the BRM database and Pipeline Manager, install and configure Pipeline Manager, create your AQ database queues, and configure the Oracle DM to publish customer events to the queues. See "Configuring Your AQ Database Queues".

How Account Synchronization Works with Pipeline Manager

The Oracle DM notifies Pipeline Manager when account information changes, such as when a CSR adds, cancels, or modifies an account or when an adjustment is applied to an account balance. The Oracle DM sends information about updates through an Oracle AQ database queue, and Pipeline Manager retrieves the information from the queue. For more information about the queue, see "About the Database Queues".

Note:

When an account is created, the Oracle DM notifies Pipeline Manager about the new account, but the account details (such as the account's charge offers, discount offers, and other account information) are not loaded into the Pipeline Manager's memory until the first call data record (CDR) is rated for the account. Pipeline Manager only requires the account details once the account has some usage that must be rated.

The Oracle DM can send any event data to Pipeline Manager. Pipeline modules register to receive events through the DAT_Listener module. When a module receives a business event, it can either use the enqueued event data for processing or access the BRM database for the most current data.

All business events sent to Pipeline Manager are stored in the AQ database queue. If Pipeline Manager terminates, the Oracle DM continues to send events to the queue. When Pipeline Manager restarts, it retrieves the events from the queue. Likewise, if the Oracle DM terminates, Pipeline Manager continues to retrieve events already in the queue.

If billing runs while Pipeline Manager starts, events are queued while the DAT modules initialize. Events are only processed after the DAT modules are ready.

Figure 46-1 shows the data flow from BRM to Pipeline Manager update.

Figure 46-1 Data Flow from BRM to Pipeline Manager

Description of "Figure 46-1 Data Flow from BRM to Pipeline Manager"

Account data is synchronized between BRM and Pipeline Manager as follows:

1. An event listed in the event notification file is generated, triggering a call to the opcode associated with that event in the list.

2. One of the following actions occurs:

   • If the event is associated with the PCM_OP_IFW_SYNC_PUBLISH_EVENT opcode, it is passed to the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode for modification. The policy opcode passes the event and any modifications to the Payload Generator External Module (EM).

     See "About the Synchronization Opcodes".

   • If the event is not associated with PCM_OP_IFW_SYNC_PUBLISH_EVENT, it is sent directly to the Payload Generator EM.

3. The Payload Generator EM collects events in its payload until they compose a complete business event.

   See "About the EAI Framework".

4. When the business event is complete, the Payload Generator EM sends it to the Oracle DM.

   See "About the Oracle DM and Synchronization".

5. The Oracle DM sends the business event to the AQ database queue.

   See "About the Database Queues".

6. DAT_Listener retrieves the business event from the database queue and sends the event to pipeline modules that are registered for that event.

   See "About the DAT_Listener Module".

7. The module uses the event as needed.

About the EAI Framework

The Oracle DM works with the Enterprise Application Integration (EAI) framework. You use the EAI framework to define business events for synchronization, capture the BRM events that make up the business events, and send the completed business events to the Oracle AQ database queue.

The EAI framework consists of the following components:

• BRM event notification

  When specific BRM events occur, event notification automatically triggers calls to opcodes that send the event to the Payload Generator EM.

  You map BRM events to opcodes using an event notification file. The default event notification file (BRM_home/sys/data/config/pin_notify_ifw_sync) provided with the BRM installer lists the BRM events required by Pipeline Manager. You can change the list of BRM events in the file to meet your business needs. You must load the event notification file into the database before account synchronization can start. See "Using Event Notification" in BRM Developer's Guide for more information.

• The Payload Generator EM

  The Payload Generator EM collects BRM events until they form a complete business event, generates the data necessary to publish business events, and sends the business events to the Oracle DM.

  The data required to create a complete business event is specified in a payload configuration file. The default payload configuration file (BRM_home/sys/data/config/payloadconfig_ifw_sync.xml) provided with the BRM installer defines the business events that Pipeline Manager needs. You can add or remove business events from the file. See "Configuring Business Events" in BRM Developer's Guide for more information.

The Payload Generator EM notifies the Oracle DM when business events occur, such as account creation, charge offer purchase, and account balance adjustment. As soon as the Payload Generator EM collects all BRM events that belong to a specific business event, it sends the business event payload to the AQ database queue.

Although the Oracle DM relies on the EAI framework, you do not need to install EAI Manager separately. All necessary EAI files are included with the BRM installer.

About the Synchronization Opcodes

Account synchronization uses a set of opcodes to modify the BRM events that form business events. The BRM events are associated with the PCM_OP_IFW_SYNC_PUBLISH_EVENT opcode in your system's event notification file. When these BRM events occur, PCM_OP_IFW_SYNC_PUBLISH_EVENT is called to pass them to the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode for processing.

You can customize the BRM events based on your business needs using the policy opcode.

After processing the BRM events, the opcodes pass them to the EAI framework publishing opcode, which compiles them into business events to publish to the AQ database queue.

Tip:

Not all BRM events that form business events must be passed through the synchronization opcodes. If you do not need to customize the BRM events, associate them with the EAI framework publishing opcode, PCM_OP_PUBLISH_GEN_PAYLOAD (number 1301), in your system's event notification file instead. This opcode is internal to BRM.

About the Oracle DM and Synchronization

The Oracle DM sends business events to the database queue. You define how the DM connects to the database queue and which business events to send to the queue through two configuration files:

• The Oracle DM configuration file (BRM_home/sys/dm_oracle/pin.conf) specifies how to connect to the AQ database queue.

• The BRM_home/sys/dm_oracle/aq_event_map specifies the business events to send to your AQ database queue.

  Note:

  If your system contains multiple schemas, you must install and configure an Oracle DM for the primary schema. Optionally, you can also install an Oracle DM for each secondary schema.

When the Oracle DM receives a business event, it does the following:

1. Determines whether to send the business event to the AQ database queue by reading the aq_event_map file.

2. Publishes the entire content of the business event to the AQ database queue.

3. Sets the business event in the AQ database queue to a READY state. See "About Event Status Flags".

About the Database Queues

The account synchronization process uses an AQ database queue to pass business events from the Oracle DM to Pipeline Manager. The AQ database queue enables the Oracle DM to pass events asynchronously, so BRM and Pipeline Manager are not required to be running at the same time.

About Creating Database Queues

The BRM installer automatically creates a default queue in a specified database schema. You can create additional AQ database queues to meet your business needs using the pin_publish_aq_oracle.pl script, which is included with the BRM installation. See "pin_publish_aq_oracle.pl" for more information.

When creating AQ database queues, you specify the following:

• The database schema in which to create the queue.

  You can create the queue in your BRM database, the Pipeline Manager database, or a separate database.

• The name of the queue and queue table.

• The tablespace in which to create the queue.

  You can create the queue in an existing tablespace or in its own separate tablespace. For optimal performance in production systems, create the queue in its own tablespace.

The number of queues to create depends on your system's configuration. Each Pipeline Manager instance connects to its own database queue. Therefore, if your system contains only one instance of Pipeline Manager, create only one database queue. If your system contains two instances of Pipeline Manager, create two database queues.

In multischema systems, each BRM database schema has one corresponding instance of Pipeline Manager and one corresponding database queue.

About the DAT_Listener Module

Pipeline Manager uses DAT_Listener to retrieve business events from the AQ database queue. When Pipeline Manager is running, DAT_Listener continuously checks the queue for events to process.

When DAT_Listener finds an event to process, it does the following:

1. Dequeues the event from the database queue.

2. Sets the event in the queue to a PROCESSED state.

3. Determines where to route the event by using the Pipeline Manager registry.

4. Sends the event to the appropriate pipeline module.

The DAT_Listener module can control whether Pipeline Manager processes business events or CDRs by interleaving the two processes. See "About Controlling the Business Event Backlog" for more information.

About Using Multiple Threads to Dequeue Events

By default, DAT_Listener uses one thread for dequeuing events. All events in the queue are processed in the order in which they are queued.

You can generate additional threads by using the DAT_Listener EventThreadAllocation registry entry:

• You can generate separate threads for processing different business events. This can enhance performance when the type of business event, such as RecycleRequest business events, takes longer to process.

• You can generate additional threads for the same type of business event. This can further enhance performance when multiple business events of the same type are queued in succession.

A new thread can begin processing an event as soon as processing for the previous event has begun.

For example, the following registry entry will generate four threads: one thread for RecycleRequest business events, two threads for OpenNewActgCycle business events, and one default thread (for which no entry is required) for all other types of events:

EventThreadAllocation
{
  RecycleRequest = 1
  OpenNewActgCycle = 2
}

Based on this registry configuration, if the following events are queued in this order:

1. RecycleRequest #1

2. CycleForward #1

3. OpenNewActgCycle #1

4. OpenNewActgCycle #2

5. OpenNewActgCycle #3

6. OpenNewActgCycle #4

7. CycleForward #2

8. RecycleRequest #2

9. CycleForward #3

They are processed during account synchronization in this order:

1. The RecycleRequest thread starts processing RecycleRequest event #1.

2. The default thread starts processing CycleForward event #1.

3. Two OpenNewActgCycle threads process OpenNewActgCycle events #1 through #4, in order.

   For example, thread 1 processes event #1 and thread 2 processes event #2. Whichever thread finishes first processes event #3, and so on.

4. When processing starts for OpenNewActgCycle event #4, the default thread starts processing CycleForward event #2 (assuming it has completed CycleForward event #1).

5. When processing starts for CycleForward event #2, the RecycleRequest thread starts processing RecycleRequest event #2 (assuming it has completed RecycleRequest event #1).

6. When processing starts for RecycleRequest event #2, the default thread starts processing CycleForward event #3 (assuming it has completed CycleForward event #2).

You can allocate only one thread for recycle requests.

Dequeuing in Batches

Dequeuing business events from the Account Synchronization queue takes longer than sending them to Pipeline Manager. To shorten the time it takes to process business events, DAT_Listener dequeues business events in batches. It then sends one event at a time to Pipeline Manager.

DAT_Listener retrieves events in batches only for events that require account synchronization, such as account data changes. These are the most frequent types of business events sent through the queue. Other events—for example, those that invoke a process such as a recycling job—continue to be dequeued one at a time.

If a business event in a batch of dequeued events contains an error, all events in the batch are rolled back in BRM, and Pipeline Manager is shut down. Shutting down Pipeline Manager clears the batch of business events from the pipeline memory. After you correct the error and stop and restart Pipeline Manager, BRM resends the business events to Pipeline Manager.

About Disconnecting DAT_Listener from the Queue

You can keep Pipeline Manager online when you tune or shut down the queuing database by disconnecting DAT_Listener from the queue. You can then reconnect the module to the queue after you finish making changes to the database.

When you disconnect DAT_Listener, it performs the following actions:

1. Waits for the total counter of active threads to become 0.

2. Disconnects each active thread:

   • If a thread is currently processing an event, DAT_Listener waits for the event to finish, inactivates the thread, and decrements the counter.

   • If a thread is not currently processing an event, DAT_Listener inactivates the thread and decreases the counter.

3. When the counter becomes 0, DAT_Listener wakes up from the wait state.

   It returns to the caller that all connections between it and the database queue have been terminated.

When you reconnect DAT_Listener, it reconnects to the queuing database and activates all threads.

You control the connection between DAT_Listener and the database queue by using DAT_Listener semaphores.

About Account Synchronization in a Multischema System

When you use a multischema system, you set up an instance of Pipeline Manager for each database schema. On one instance of Pipeline Manager, you configure the multischema account router module. This module keeps track of which database schema each account belongs to.

To set up account synchronization for multiple database schemas, create an Oracle DM on the primary BRM installation machine and, optionally, on your secondary BRM installation machines. You also do the following:

• Add an AQ database queue for each BRM database schema.

  Each Oracle DM connects to only one database schema and uses schema qualifications to put event messages in queues in other database schemas.

• Configure an instance of Pipeline Manager for each BRM database schema.

  Each instance of Pipeline Manager has a DAT_Listener module that retrieves events for that instance. You specify the events for each instance in the DAT_Listener registry.

  Note:

  Install an Oracle DM instance and have a corresponding instance of Pipeline Manager for every BRM database schema. How you configure multiple database schemas depends on your business needs and should be determined by your system and database administrators.

About Controlling the Business Event Backlog

When you use Pipeline Manager for batch rating, the AQ database queue can become backlogged with business events waiting to be processed. This can delay account synchronization and slow Pipeline Manager performance, causing more CDRs to be suspended.

To control the number of events waiting to be processed, you can configure DAT_Listener to interleave CDR and business event processing. See "About Interleaved Processing" for more information.

Why Event Backlog Occurs

Event backlog can occur for the following reasons:

• When Pipeline Manager modules update account data, they lock the accounts they update in each transaction. When more than one transaction must access the same account, the transactions must wait until the account is unlocked. If the account stays locked for a relatively long time, business events can become backlogged while they wait for processing.

• When business events arrive that change account information during CDR processing, Pipeline Manager must update its memory before continuing to rate events in the CDR. This requires accessing the database, which increases the number of times the accounts are locked. Processing business events and CDRs concurrently could require multiple updates, reducing overall Pipeline Manager performance.

• When an account is being billed, Pipeline Manager must receive a business event notifying it that billing is complete before it can process new event data records (EDRs) for the account. If a billing business event is waiting to be processed behind a backlog of other events, many new EDRs for the account might require suspending until the billing event is processed. Each time a suspended EDR is recycled, a new business event is added to the AQ database queue.

About Interleaved Processing

You can configure Pipeline Manager to process CDRs and business events exclusively rather than concurrently. Exclusive processing reduces the likelihood that you will need to recycle events due to delayed synchronization or to stop Pipeline Manager to catch up on business event processing.

With interleaved processing, Pipeline Manager interleaves the processing of business events and CDRs so it can process multiple business events before rating CDRs and rate multiple CDRs before updating Pipeline Manager memory. This balances the event backlog and improves processing time by decreasing the number of times Pipeline Manager must access the database and lock accounts.

DAT_Listener controls whether business events or CDRs are processed based on the following criteria:

• How many business events are waiting to be processed in the AQ database queue.

• The time that Pipeline Manager has been currently processing either business events or CDRs.

Depending on how much control you want over the interleaving process, you can use the first or both of these criteria. See "About Setting Processing Thresholds".

You specify the thresholds for event processing in the DAT_Listener module registry.

If you configure the number of events and the processing time, DAT_Listener performs the following actions to control interleaved processing:

1. Periodically checks the number of business events waiting to be processed in the AQ database queue and tracks the amount of time that Pipeline Manager has been currently processing either business events or CDRs.

2. Stops pipeline CDR processing when the number of business events in the queue reaches the maximum threshold or when the maximum CDR processing time is reached, whichever comes first.

   DAT_Listener stops Pipeline Manager by sending a stop command to the pipeline controller. This command suspends CDR processing but allows business event processing to proceed.

3. Dequeues business events and sends them to pipelines for processing.

4. Stops dequeuing business events when the number of business events in the AQ database queue reaches the minimum threshold or when the maximum business event processing time is reached, whichever comes first.

5. Restarts Pipeline Manager CDR processing by sending a start command to the pipeline controller.

The Oracle DM continues to send business events to the queue while Pipeline Manager processes CDRs.

When tracking the number of business events in the queue, DAT_Listener counts only the business events with a state of READY. It ignores all other business events.

About Setting Processing Thresholds

To configure basic process interleaving, you set the minimum and maximum business event thresholds. For more control over CDR and business event interleaving, you can also set the maximum CDR and business event processing times.

For example, if you typically process fewer events in the middle of the night, reaching the maximum number of business events in the queue might take longer. Account synchronization will be delayed during this time, and you might have a higher incidence of CDRs that need suspending or rerating. In this case, you limit the time spent on CDR processing. When this time threshold is reached, DAT_Listener switches to business event processing even if the number of events in the queue has not reached the maximum.

Consider limiting business event processing time if there are certain times when many business events accumulate in the queue (for example, when you shut down Pipeline Manager for an extended period). When you stop and restart Pipeline Manager, rather than waiting until the minimum business event threshold is reached, Pipeline Manager switches to CDR processing when the maximum business event process time is reached.

Note:

DAT_Listener does not check whether CDRs are waiting to be processed. It checks only for business events and processing times. Therefore, if there are no CDRs to process, DAT_Listener waits until either the CDR processing time threshold or the maximum number of business events is reached before switching to business event processing. If this wait period is too long, you can update the DAT_Listener registry to switch from CDR to business event processing.