1. System Administrator's Guide
  2. Synchronizing BRM Data with Other Applications
  3. Configuring Your AQ Database Queues

48 Configuring Your AQ Database Queues

You can create Oracle Advanced Queuing (AQ) database queues so you can synchronize data between Oracle Communications Billing and Revenue Management (BRM) and Elastic Charging Engine (ECE), and between BRM and external customer relationship management (CRM) systems.

Topics in this document:

Tasks for Setting Up AQ Database Queues

You create Oracle Advanced Queuing (AQ) database queues so you can synchronize:

To set up AQ database queues in your system:

  1. Configure your database for Oracle Advanced Queuing. See "Configuring Your Database for Advanced Queuing".

  2. Install BRM, which creates the default queues required to synchronize pricing data between BRM and external CRMs.

    See "Installing BRM" in BRM Installation Guide for more information.

  3. Install Elastic Charging Engine (ECE) and then run one or both ECE postinstallation scripts, which create the default queues required to synchronize account data between BRM and ECE:

    • post_Install.pl creates the Notification queue, Suspense queue, and Acknowledgment queue in your WebLogic system.

    • kafka_post_install.sh creates the Notification topic and Suspense topic in your Kafka Server. This script also creates other topics needed for 5G-enabled ECE systems.

    See "Installing Elastic Charging Engine" in ECE Installation Guide for more information.

  4. Create additional AQ database queues, if necessary. See "Creating Additional Queues for Multischema BRM Systems".

  5. Configure event notification to synchronize BRM account and pricing data. See "Configuring Event Notification for Account and Pricing Synchronization".

  6. Configure EAI payload for synchronizing BRM account and pricing data. See "Configuring EAI Payload for Synchronization".

  7. Specify the name of the primary schema in which to manage AQ database queues. See "Configuring the Primary Schema for AQ Queues".

  8. Configure the Oracle DM to use the business event-to-queue mapping file. See "Connecting Oracle DM to Queue Mapping File".

  9. Map business events to AQ database queues. See "Mapping Business Events to Database Queues".

Configuring Your Database for Advanced Queuing

Before installing BRM, you must configure your database for Oracle AQ. Perform the following on each Oracle database in your system:

  1. Open the Oracle_home/database/init.ora file in a text editor, where Oracle_home is the directory in which you installed the Oracle database software.

  2. Set the COMPATIBLE parameter to the Oracle database version number.

    See "Database Servers" in BRM Compatibility Matrix for the list of supported database versions.

  3. Specify one Oracle Queue Monitor process (QMN) by setting the AQ_TM_PROCESSES parameter to 1.

    By default, QMN removes any processed events that are over an hour old from the queue.

  4. Save and close the file.

  5. Using SQL*Plus, log in to your database as the SYS user and grant AQ privileges to each schema user:

    % sqlplus sys@databaseAlias as sysdba
Enter password: password
  
SQL> grant execute on dbms_aq to schema_user_name;
  
Grant succeeded.
  
SQL> grant execute on dbms_aqadm to schema_user_name;
  
Grant succeeded.  
  
SQL> grant select on sys.gv_$aq to schema_user_name;
  
Grant succeeded.  
  
SQL> grant execute on dbms_lock to schema_user_name;
  
Grant succeeded.
  
SQL> grant execute on dbms_aqin to schema_user_name;
  
Grant succeeded.
  
SQL> grant execute on sys.dbms_aqin to schema_user_name;
  
Grant succeeded.

    where schema_user_name is the user name for the schema to which you are granting privileges.

  6. Initialize the database instance with your changes by stopping and restarting the Oracle database.

Creating Additional Queues for Multischema BRM Systems

If you have a multischema BRM system, you must manually create additional queues for each secondary BRM schema in your system. To do so, use the pin_publish_aq_oracle.pl utility. For more information about the utility's syntax and parameters, see "pin_publish_aq_oracle.pl"

To create additional queues for a multischema BRM system, do this for each secondary schema:

  1. Verify the default queue storage and retention time settings in the BRM_home/apps/pin_publish_aq/create_aq_queue.conf file.

  2. Enter the following command, which logs you in as the pin user: 

    su - pin

    Note:

    To create queues, the pin user must have Oracle AQ privileges.

  3. Create the AQ database queues required for your needs by running this command:

    pin_publish_aq_oracle.pl create -q queueName -t tableName -l /@database_alias

    where:

    • queueName is the name of the queue to create.

    • tableName is the name of the table to create.

    • database_alias is the BRM database alias of the database to which you are adding a queue. If you omit the -l /@database_alias parameter, the utility will prompt you for this information.

  4. Run the following command for each queue to verify that they were created successfully. This command attempts to enqueue and dequeue 20 test events: 

    pin_publish_aq_oracle.pl test -q queueName -l /@database_alias

    The utility enqueues and dequeues 20 test events.

    Note:

    You only need to test a queue after it has first been created.

  5. Run the following command for each queue to generate a summary report that displays the state of each event in the queue:

    pin_publish_aq_oracle.pl report -r summary -q queueName -l /@database_alias

    If successful, the report lists the 20 events with a processed state:

    Tue Feb 04                                               page 1
                      Event Summary Report 
Evt. Stat  Event Name                        Event Count 
---------  --------------------------------  ----------- 
PROCESSED  LongTestEvent                              10 
           ShortTestEvent                             10 
*********                                    ----------- 
sum                                                   20

    If unsuccessful, drop and re-create the queue and queue table.

Configuring Event Notification for Account and Pricing Synchronization

The event notification file specifies all events that trigger event notification in your BRM system. The file maps each event to the opcode to run when the event occurs. When called, the opcode sends the BRM event to the Payload Generator.

Note:

BRM stores your event notification list in the /config/notify object.

To configure event notification for account and pricing synchronization:

  1. Open the appropriate event notification file:

    • ECE_home/brm_config/pin_notify: Lists the events for synchronizing account data with ECE

    • BRM_home/sys/data/config/pin_notify_ifw_sync: Lists the event for synchronizing account data with Pipeline Manager

    • BRM_home/sys/data/config/pin_notify_crm_sync: Lists the events for synchronizing pricing data with external CRMs

    To synchronize BRM with multiple applications, you must merge the files together. See "Merging Event Notification Lists" in BRM Developer's Guide for more information.

  2. (Optional) If you defined new business events to synchronize, edit your final event notification file to include all new events.

  3. Load your final event notification file into the BRM database using the load_pin_notify utility.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Configuring EAI Payload for Synchronization

You define which notification events the Payload Generator EM uses to form a complete business event using the payload configuration file. Add or remove business events from the file to accommodate your business needs.

To configure the EAI payload for synchronization:

  1. Open one of these payload configuration files:

    • ECE_home/brm_config/payloadconfig_ece_sync.xml: Use this file to synchronize account data with ECE

    • BRM_home/sys/data/config/payloadconfig_ifw_sync.xml: Use this file to synchronize account data with Pipeline Manager

    • BRM_home/sys/eai_js/payloadconfig_crm_sync.xml: Use this file to synchronize pricing data with external CRMs

    To support both account and pricing synchronization, you must merge the files together.

  2. Add or remove business events as needed. See "Payload Configuration File Syntax" in BRM Developer's Guide for more information.

  3. Save and close the final file.

  4. Stop and restart the Payload Generator EM:

    cd BRM_home/bin 
pin_ctl bounce eai_js

Configuring the Primary Schema for AQ Queues

You configure the primary schema in which to create AQ database queues using the create_aq_queue.conf file. The pin_publish_aq_oracle.pl utility uses this file when creating, dropping, and managing AQ database queues.

To specify the primary schema in which to create AQ database queues:

  1. Open the BRM_home/apps/pin_publish_aq/create_aq_queue.conf file in a text editor.

  2. Specify the primary schema name in the primary_schema parameter: 

    $primary_schema = "schemaName";

    where schemaName is the name of the local schema or the schema containing the queue where events from other schemas are enqueued. In multischema systems, this is usually the schema where the Acknowledgment queue resides.

  3. Save and close the file.

Connecting Oracle DM to Queue Mapping File

During installation, the Oracle DM installer generates a pin.conf configuration file that specifies how to connect to your BRM database and AQ database queue. The installer populates the connection entries with values from your pin_setup.values file and provides default information for the other configuration entries. Before you start the Oracle DM, verify that the file contains accurate data for connecting to your BRM database and AQ database queue.

For each instance of the Oracle DM, edit your BRM_home/apps/dm_oracle/pin.conf file. In the file's aq_event_map_file entry, specify the name and location of the event-to-queue mapping (aq_event_map) file: 

-dm aq_event_map_file ./aq_event_map

Note:

In multischema systems, each BRM database schema might have its own Oracle DM. Verify that each Oracle DM pin.conf file contains accurate information for its associated schema and AQ database queue.

Mapping Business Events to Database Queues

You configure which events the Oracle DM sends to each AQ database queue by editing the aq_event_map file. This file must specify the names of all queues in your system and which events to send to each queue.

Note:

  • Oracle DM sends only business events defined in the payloadconfig file to an AQ database queue.

  • Oracle DM does not send events to AQ database queues until you edit the aq_event_map file.

To map business events to AQ database queues:

  1. Open the BRM_home/sys/dm_oracle/aq_event_map file in a text editor.

  2. Add an entry for each AQ database queue in your system using the following syntax:

    schema_name.queue_name
{
  criteria
}

    where:

    • schema_name is the name of the database schema containing the queue. Include the schema name only if the queue resides in a remote database schema. Omit the schema name if the queue resides in the local database schema.

      In multischema systems, each instance of the Oracle DM connects to only one database queue in a schema. That schema is the DM's local schema. In some cases, the Oracle DM receives an event that belongs to a queue in a different schema (for example, when you move an account from one schema to another). Oracle AQ uses the queue name entries in the aq_event_map file to send the events to the appropriate queue.

    • queue_name is the name you assigned to the AQ database queue.

    • criteria specifies the events to send to the AQ database queue. You can configure the Oracle DM to send all business events, only events from a specific database schema, or only specific event types. Table 48-1 shows the syntax for each criteria.

      Table 48-1 Syntax to Add Events to Queues

      To Send This Use This Syntax Example

      All business events

      ALL

      ALL

      Only business events from a specific database schema

      0.0.0.x

      0.0.0.1

      Only specific event types

      eventName

      CustCreate

      ProductCancel

      Excluding specific event types

      !eventName

      !CustCreate

      !ProductCancel

      A specific event from a specific database

      0.0.0.x AND

      eventName

      0.0.0.1 AND

      ProductCancel

      Excluding a specific event from a specific database

      0.0.0.x AND

      !eventName

      0.0.0.1 AND

      !ProductCancel

      For example, to send all business events from BRM database schema 0.0.0.1 to the local EXAMPLE_1 queue and only CustCreate events to the EXAMPLE_2 queue, which resides in a remote database schema, use the following syntax:

      EXAMPLE_1
{
  0.0.0.1
}
  
schema_name.EXAMPLE_2
{
  CustCreate
}

  3. Save and close the file.

Mapping Events in Systems Containing Multiple aq_event_map Files

In a multischema system, each BRM instance contains an aq_event_map file. The aq_event_map file of the primary Oracle DM must include one or more queue entries for every database schema in your system.

For example, if you use three database schemas, the entries in the aq_event_map file of the primary Oracle DM, which is connected to schema 0.0.0.1, would look like this: 

EXAMPLE_ROUTER_QUEUE
{
 CustCreate
 ServiceLogin
 CustDelete
}
  
EXAMPLE_QUEUE_1     # queue on local database schema
{
  0.0.0.1
}
0.0.0.2.EXAMPLE_QUEUE_2     # queue on remote database schema
{
  0.0.0.2
}
0.0.0.3.EXAMPLE_QUEUE_3     # queue on remote database schema
{
  0.0.0.3
}

Any aq_event_map file on a secondary installation machine must include entries for only local queues. For example, the entry in the aq_event_map file of a secondary Oracle DM connected to schema 0.0.0.2 would look like this: 

IFW_SYNC_QUEUE_2     # queue on local database schema
{
  0.0.0.2
}