Skip Headers
Oracle® Communications Billing and Revenue Management Installation Guide
Release 7.5

E16706-13
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

22 Installing and Configuring Account Synchronization

This chapter describes how to install and configure Oracle Communications Billing and Revenue Management (BRM) Account Synchronization Manager. Anyone who installs, configures, or administers Account Synchronization Manager should read this document.

Before installing Account Synchronization Manager, you should be familiar with how a BRM wireless system and account synchronization work. See the following:

About Installing Account Synchronization Manager

Before installing Account Synchronization Manager, you should be familiar with BRM concepts and architecture. See BRM Concepts.

Important:

Account Synchronization Manager is an optional feature that requires a separate license.

System Requirements

Account Synchronization Manager is available for the HP-UX IA64, Oracle Solaris, Linux, and AIX operating systems.

Software Requirements

Before installing Account Synchronization Manager, you must install the following:

Information Requirements

You need the following information about your existing BRM system during the Account Synchronization Manager installation:

  1. Queuing database alias name

  2. Queuing database schema user name and password

  3. Queuing database schema name and retention time for the queue in the schema

Account Synchronization Manager Components

The Account Synchronization Manager components include a Connection Manager (CM), a Data Manager (DM), and an EAI Java server. When you install Account Synchronization, you can install all the components on the same machine (typical install) or install them individually on the same or different machines (custom install).

When you install Account Synchronization Manager, the installation program updates your BRM_Home/setup/pin_setup.values files with information about the Account Synchronization components.

Important:

If you install Account Synchronization components individually but on the same machine, the pin_setup files are overwritten with each subsequent install.

To preserve important information, such as port numbers and host names, save a copy of your pin_setup.values file with another name before installing a new component. For example, use the file name pin_setup_orig.values.

Account Synchronization contains the following components:

  • Account Synchronization CM: The Account Synchronization CM is a CM module that contains the EAI framework Facilities Module (FM) and the Account Synchronization FMs.

    Important:

    The Account Synchronization CM is dependent on the CM and must be installed on all hosts on which the CM will run.
  • Account Synchronization DM: The Account Synchronization DM (dm_ifw_sync) contains files to start and stop the Account Synchronization DM and perform other Account Synchronization DM functions. This component has no dependencies.

  • Account Synchronization EAI Java server: This Java server contains the files that start and stop the EAI Java server and perform other EAI Java server functions such as merging payload configuration files. This component has no dependencies.

    Important:

    If a Payload Generator External Module (another EAI Java server) has already been installed (as part of installing the EAI Manager or another EAI-based publisher), the Account Synchronization EAI Java server must be installed on the same host where the existing EAI server is installed.

You can run the Account Synchronization DM and the Payload Generator External Module (EM) on computers other than the computer on which the CM is running. To do this, you must run the Account Synchronization installation program on each computer that hosts one or more of these features.

Installing and Configuring Account Synchronization

To install Account Synchronization:

  1. Configure your database machines for advanced queuing.

    See "Configuring Database Machines for Advanced Queuing".

  2. Install Account Synchronization Manager.

    See "Installing Account Synchronization Manager".

  3. Create additional Account Synchronization queues.

    See "Creating Additional Account Synchronization Queues".

  4. If your system contains queues in multiple database schemas, grant execute permission for acct_sync.

    See "Granting Execute Permission for acct_sync".

  5. Configure the EAI payload for Account Synchronization.

    See "Configuring the EAI Payload for Account Synchronization".

  6. Enable event notification.

    See "Configuring Event Notification for Account Synchronization".

  7. Configure Account Synchronization.

    See "Configuring Account Synchronization".

  8. Configure the DAT_Listener module.

    See "Configuring the DAT_Listener Module".

  9. Set up service-level bill items.

    See "Setting Up Service-Level Bill Items".

  10. Enable BRM to audit GSM (Global System for Mobile Communication) objects.

    See "Turning On Object Auditing".

  11. Configure Account Synchronization for multiple database schemas.

    See "Configuring Account Synchronization for Multiple Database Schemas".

Configuring Database Machines for Advanced Queuing

Before you install Account Synchronization Manager, you must configure all queuing database machines for advanced queuing.

Perform the following on each queuing database machine in your system:

  1. Open the Oracle_Home/dbs/initSID.ora file in a text editor, where Oracle_Home is the directory in which you installed the Oracle Database.

  2. Set the compatible parameter to your Oracle database version.

    Important:

    If you use an entry lower than 10.0, your BRM and Pipeline Manager systems fail.
  3. Specify one queue monitor process (QMn) by setting the aq_tm_process parameter to 1.

    The queue monitor process removes from the queue any processed events that are over an hour old.

  4. Save and close the file.

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

    % sqlplus sys/password@databaseAlias
      
    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.
      
    

    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.

Installing Account Synchronization Manager

Note:

If you have already installed the product, features that are already installed cannot be reinstalled without uninstalling them first. To reinstall a feature, uninstall it and then install it again.

To install Account Synchronization Manager:

  1. Download the Account Synchronization Manager software package (7.5.0_AccountSynchTool_platform_opt.bin) for the appropriate platform from the Oracle software delivery Web site (https://edelivery.oracle.com) to a temporary directory (temp_dir).

    Important:

    • If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server.

    • You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid ”Out of Memory” error messages in the log file. For information, see "Increasing Heap Size to Avoid ”Out of Memory” Error Messages".

  2. Go to the directory where you installed the Third-Party package and source the source.me file.

    Note:

    You must source the source.me file to proceed with installation, otherwise ”suitable JVM not found” and other error messages appear.

    Bash shell:

    source source.me.sh
      
    

    C shell:

    source source.me.csh
      
    
  3. Go to temp_dir and enter the following command:

    7.5.0_AccountSynchTool_platform_opt.bin
      
    

    where platform is the operating system name.

    Note:

    You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.
  4. (Optional) To install Account Synchronization features separately, either on this computer or on another computer, select custom install when asked to specify the setup type.

    Select the components you are installing by entering their respective numbers. The features are:

    • AcctSync_CM

    • AcctSync_DM

    • AcctSync_EAI_JS

  5. Click Next.

  6. Follow the instructions displayed during installation.

    The default installation directory for Account Synchronization Manager is opt/portal/7.5.

    Note:

    The installation program does not prompt you for the installation directory if BRM or Account Synchronization Manager is already installed on the machine and automatically installs the package at the BRM_Home location.
  7. Go to the directory where you installed the Account Synchronization Manager package and source the source.me file:

    Bash shell:

    source source.me.sh
      
    

    C shell:

    source source.me.csh
      
    
  8. Go to the BRM_Home/setup directory and run the pin_setup script.

    Note:

    The pin_setup script starts all required BRM processes.

    The script creates a queue in the specified database schema, configures your pin.conf files, and starts all of your BRM processes.

  9. Stop the Account Synchronization DM process.

    For information, see "Starting and Stopping the Account Synchronization DM".

Creating Additional Account Synchronization Queues

The Account Synchronization Manager installer automatically creates a default queue in a specified database schema. If your system requires multiple queues, create additional queues by manually running the pin_ifw_sync_oracle utility.

Important:

To avoid system errors, do not run Pipeline Manager while running the pin_ifw_sync_oracle utility.

To create an additional database queue:

  1. Verify the default queue storage and retention time settings in the create_ifw_sync_queue.conf file.

    For more information, see:

  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 Advanced Queuing (AQ) privileges.
  3. Run the following command, which creates a new queue:

    pin_ifw_sync_oracle.pl create -q queue_name -t queue_table -l user/password@database_alias
      
    

    where:

    • queue_name is the name of the new queue. If you omit this parameter the utility creates a database queue named IFW_SYNC_QUEUE.

      Important:

      In multischema systems, all queues in a schema must have unique names, but the same queue name can be used across multiple schemas.
    • queue_table is the name of the database table that contains the queue_name. If you omit this parameter, the utility creates a queue table named IFW_SYNC.

    • user is a valid user name for accessing the database.

    • password is the password for the specified user. If you omit this parameter, the utility will prompt you for this information.

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

  4. Run the following command, which verifies that the queue was created and functions properly by attempting to enqueue and dequeue 20 test events:

    pin_ifw_sync_oracle.pl test -q queue_name -l user/password@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, which generates a summary report that displays the state of each event in the queue:

    pin_ifw_sync_oracle.pl report -r summary -q queue_name -l user/password@database_alias
        
    

    If the tests were 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, you must drop and then recreate the queue and queue table. For information, see "Dropping the Queue and Queue Tables".

For more information about the pin_ifw_sync_oracle utility, see "pin_ifw_sync_oracle".

Creating an Acknowledgment Queue for Account Migration Manager

In a system containing Account Migration Manager, an acknowledgment queue pushes AMM-related events. Multiple pipelines, associated with different schemas, can connect to this one acknowledgment queue and send acknowledgment events. If events are enqueued into an acknowledgment queue that resides in a different schema, you must specify the schema name in the create_ifw_sync_queue.conf file.

To modify the default schema name in the $primary_schema parameter:

  1. Open the BRM_Home/apps/pin_ifw_sync/create_ifw_sync_queue.conf file in a text editor.

  2. Add or modify the following entry:

    $primary_schema = "schema_name"; 
    
      
    

    where schema_name is the name of the schema that contains the acknowledgment queue into which events are enqueued. Use pin if the acknowledgment queue resides in the local schema.

    Note:

    For example, if the acknowledgment queue is configured in schema pin01 and the events from schema pin02 have to be enqueued into that acknowledgment queue:
    $primary_schema = "pin01"
    
  3. Save and close the file.

  4. To enable access to the schema where the acknowledgment queue resides:

    1. Create a new file_name.sql file.

    2. Add the following commands to file_name.sql:

      set serveroutput on;
      BEGIN
      EXECUTE IMMEDIATE 'GRANT EXECUTE ON PIN_EVENT_TY TO schema_name ;
      DBMS_AQADM.GRANT_QUEUE_PRIVILEGE(
      privilege => 'ALL',
      queue_name => 'queue_name',
      grantee => 'schema_name',
      grant_option => FALSE);
      EXECUTE IMMEDIATE 'GRANT SELECT ON AQ$queue_table TO schema_name';
      EXECUTE IMMEDIATE 'GRANT UPDATE ON AQ$queue_table TO schema_name';
      END;
         
      -------------------------------------------------------------------
        
      

      where:

      queue_name is the acknowledgment queue name.

      schema_name is the schema from which events are enqueued to the acknowledgment queue.

      queue_table is the database table that contains the acknowledgment queue.

      Note:

      Execute the GRANT statements for each schema from which events are enqueued to the acknowledgment queue.

      For example:

      BEGIN
      EXECUTE IMMEDIATE 'GRANT EXECUTE ON PIN_EVENT_TY TO PIN02 ;
      DBMS_AQADM.GRANT_QUEUE_PRIVILEGE(
      privilege => 'ALL',
      queue_name => 'IFW_SYNC_QUEUE_AMT',
      grantee => 'PIN02',
      grant_option => FALSE);
      EXECUTE IMMEDIATE 'GRANT SELECT ON AQ$IFW_SYNC_QUEUE_AMT_T TO PIN02';
      EXECUTE IMMEDIATE 'GRANT UPDATE ON AQ$IFW_SYNC_QUEUE_AMT_T TO PIN02';
      END;
        
      
  5. Open SQL *Plus by entering the following command:

    sqlplus pin/pin@ORACLE_SID
    
      
    

    where ORACLE_SID is the BRM database alias.

  6. From the schema where the acknowledgment queue is configured, run the following command:

    @file_name.sql
      
    
  7. Run the pin_ifw_sync_oracle utility. See "Creating Additional Account Synchronization Queues" for more information.

Granting Execute Permission for acct_sync

If your system contains queues in multiple database schemas, you must grant execute permission for the acct_sync package from each queuing database schema to every other queuing database schema. This enables dm_ifw_sync to forward events to queues residing on other database schemas.

Note:

If you do not have a multischema system, skip this section and go to "Configuring the EAI Payload for Account Synchronization".

To grant execute permission for acct_sync:

  1. Log in to a target database schema:

    sqlplus target_schema_user_name/password@database_alias
      
    

    where:

    • target_schema_user_name is the user name for a schema to which events are forwarded from a source schema.

    • password is the password for the target schema user name.

    • database_alias is the BRM database alias of the target schema.

  2. Grant execute privileges to the source schema:

    SQL> grant execute on acct_sync to source_schema_user_name
      
    

    where source_schema_user_name is the user name for the schema from which events are forwarded to the target.

For example, if dm_ifw_sync connects to the pin1 database schema, enable it to send an event to the pin2 schema as follows:

  1. Log in to the pin2 schema:

    sqlplus pin2/password@database_alias
      
    

    where:

    • password is the password for the pin2 schema user name.

    • database_alias is the BRM database alias of the pin2 schema.

  2. Grant execute privileges to the pin1 schema:

    SQL> grant execute on acct_sync to pin1
    

Configuring the EAI Payload for Account Synchronization

You must modify your BRM system's payload configuration file in the following situations:

For information about defining business events in the EAI payload configuration file, see BRM Developer's Guide.

Checking for Conflicts in EAI Payload Configuration Files

If your BRM system already has an EAI publisher, the Account Synchronization Manager installation program merges this file with the existing payload configuration file.

Note:

If you do not have an existing EAI publisher application, skip this section and go to "Specifying the Account Synchronization DM Database Number".

In rare cases, conflicts can occur when the Account Synchronization Manager payload configuration file is merged with an existing payload configuration file. This can happen when entries in the two original configuration files have conflicting definitions.

Important:

You must determine whether merge conflicts exist before running Account Synchronization Manager.

Compare the Account Synchronization Manager payload configuration file (BRM_Home/sys/eai_js/payloadconfig_ifw_sync.xml) with the existing payload configuration file (referenced in BRM_Home/sys/eai_js/Infranet.properties). If any of the following conditions exist, it is not possible to run both EAI publishers in the same BRM system:

  • Two different business event definitions specify the same StartEvent.

  • The same business event definitions have different values for one or more of these attributes: StartEvent, EndEvent, or Source.

  • The same business event or element definitions have different search criteria.

  • The same element definitions have different values for one or more of the following attributes: Source, PinFld, DataFrom, UseOnlyElement, or Tag.

  • The same element definitions have different OnEvent values.

Specifying the Default Payload Configuration File

If your BRM system already has an EAI publisher, you must make the payloadconfig_MergedWithIfw_sync.xml file your system's default payload configuration file.

Note:

If you do not have an existing EAI publisher application, skip this section and go to "Specifying the Account Synchronization DM Database Number".

To specify the default payload configuration file, do one of the following:

  • Change the EAI configFile entry so that it points to the merged payload configuration file:

    1. Open the BRM_Home/sys/eai_js/Infranet.properties file in a text editor.

    2. Set the infranet.eai.configFile entry to point to the BRM_Home/sys/eai_js/payloadconfig_MergedWithIfw_sync.xml file:

      infranet.eai.configFile=./payloadconfig_MergedWithIfw_sync.xml
        
      
    3. Save and close the file.

  • Rename the configuration file and the configFile entry to match each other:

    1. Change the name of the file specified in the infranet.eai.configFile entry.

      For example, change payloadconfig.xml to payloadconfig_eai.xml.

    2. Change the name of the BRM_Home/sys/eai_js/payloadconfig_MergedWithIfw_sync.xml file to match the file name specified in the infranet.eai.configFile entry.

Specifying the Account Synchronization DM Database Number

The default BRM database number for your Account Synchronization DM is 0.0.9.9. If you change your database number, you must change the value of the DB attribute in the Account Synchronization DM publisher definition.

Note:

If you did not change the default database number for your Account Synchronization DM, go to "Configuring Event Notification for Account Synchronization".

To specify the Account Synchronization DM database number:

  1. Open the BRM_Home/sys/eai_js/payloadconfig_ifw_sync.xml file, or open the merged file if you merged payload configuration files, in a text editor.

  2. Find the <PublisherDefs> section.

  3. In the Publisher DB entry, enter the correct BRM database number.

    For example, if your Account Synchronization DM database number is 0.0.9.5, change this entry:

    <PublisherDefs>
        <Publisher DB="0.0.9.9" Format="FLIST">
      
    

    to this:

    <PublisherDefs>
        <Publisher DB="0.0.9.5" Format="FLIST">
      
    
  4. Save and close the file.

Revising the Payload Configuration File When Uninstalling Account Synchronization Manager

To remove Account Synchronization elements from your system's EAI payload configuration file after uninstalling Account Synchronization Manager:

  1. Open the BRM_Home/sys/eai_js/payloadconfig_ifw_sync.xml file, or open the merged file if you merged payload configuration files, in a text editor.

  2. Find the <PublisherDefs> section.

  3. Remove the following publisher definition:

    <Publisher DB="database_number" Format="FLIST">
      
    
  4. Save and close the file.

  5. Stop and restart the Payload Generator External Module (the EAI Java server) by entering the following command from the BRM_Home/bin directory:

    pin_ctl bounce eai_js
    

Configuring Event Notification for Account Synchronization

When a BRM event that is included in a business event defined in the Account Synchronization Manager payload configuration file occurs, the EAI framework uses event notification to call the opcode that caches the BRM event in the Payload Generator. See "About Event Notification" in BRM Developer's Guide.

To configure the event notification feature:

  1. If your system has multiple configuration files for event notification, merge them.

  2. Ensure that the merged file includes the entire event notification list in the BRM_Home/sys/data/config/pin_notify_ifw_sync file.

  3. (Optional) If you defined new business events for Account Synchronization, you must edit your final event notification list to include all the BRM events in the new business events.

  4. Load your final event notification list into the BRM database.

Configuring Account Synchronization

To configure the Account Synchronization DM to connect to the BRM database and the database queue:

  1. Connect the Account Synchronization Manager's EAI framework to BRM by editing the CM configuration file (pin.conf).

    See "Configuring the CM for Account Synchronization".

  2. Map BRM business events to the appropriate database queue by editing the ifw_sync_queuenames file.

    See "Mapping Business Events to Database Queues".

  3. Connect the Account Synchronization DM to the database queue by editing the Account Synchronization DM configuration file (pin.conf).

    See "Configuring the Account Synchronization DM".

Configuring the CM for Account Synchronization

You must modify the CM pin.conf file to enable the EAI framework to notify Account Synchronization Manager when specific events occur. You should also verify that the pointer to the Account Synchronization DM specifies the correct database and port numbers.

Important:

If you use a multischema system and set up more than one CM, you must edit the configuration file for each CM.

To configure the CM for account synchronization:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.

  2. Set the enable_publish entry to 1:

    - fm_publish enable_publish 1
      
    
  3. Verify that the dm_pointer entry for dm_ifw_sync specifies the correct database number and port:

    - cm dm_pointer 0.0.9.9 ip host_name/ip_address 11999
      
    

    where:

    • 0.0.9.9 is the default Account Synchronization DM database number.

    • host_name/ip_address is the host name or IP address of the computer on which the Account Synchronization DM runs.

    • 11999 is the default Account Synchronization DM port number.

      Note:

      If you change the location of the Account Synchronization DM, you must modify this entry. For more information, see the description of using configuration files to connect and configure components in BRM System Administrator's Guide.

      Important:

      The Account Synchronization DM database number must match the number in the following entries:
      • The dm_db_no entry in the Account Synchronization DM configuration file (BRM_Home/sys/dm_ifw_sync/pin.conf).

      • The DB entry of the Account Synchronization Publisher definition in the payload configuration file (BRM_Home/sys/eai_js/payloadconfig_ifw_sync.xml).

      The Account Synchronization DM port number must match the number in the dm_port entry in the Account Synchronization DM configuration file (BRM_Home/sys/dm_ifw_sync/pin.conf).

  4. Save and close the file.

  5. Stop and restart the CM:

    • From the BRM_Home/bin directory, enter this command:

      pin_ctl bounce cm
      

Mapping Business Events to Database Queues

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

Note:

  • Only business events that are defined in the payloadconfig file can be sent to a database queue.

  • Account synchronization does not send events to queues until you edit the ifw_sync_queuenames file.

To map business events to database queues:

  1. Open the BRM_Home/sys/dm_ifw_sync/ifw_sync_queuenames file in a text editor.

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

    schema_name.queue_name
    {
      criteria
    }
      
    

    where:

    • schema_name is the name of the database schema containing the queue.

      In multischema systems, each instance of the Account Synchronization DM connects to only one database queue in only one schema. That schema is the DM's local schema. In some cases, the Account Synchronization 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 ifw_sync_queuenames file to send the events to the appropriate queue:

      • If a queue is on the local database schema, do not include schema_name in the entry.

      • If a queue is on a remote database schema, prepend the queue name with the name of the database schema to which it belongs.

    • queue_name is the name you assigned the queue when you created it. Each queue name must match the queue name in the corresponding DAT_Listener registry.

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

      Table 22-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 IFW_SYNC_QUEUE_1 queue and only CustCreate events to the IFW_SYNC_QUEUE_2 queue, which resides in another database schema, use the following syntax:

      IFW_SYNC_QUEUE_1
      {
        0.0.0.1
      }
        
      schema_name.IFW_SYNC_QUEUE_2
      {
        CustCreate
      }
        
      
  3. Save and close the file.

Mapping Events in Systems Containing Multiple ifw_sync_queuenames Files

In a multischema system, each BRM installation machine on which an instance of the Account Synchronization DM is installed contains an ifw_sync_queuenames file for that DM.

The ifw_sync_queuenames file of the primary Account Synchronization 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 ifw_sync_queuenames file of the primary Account Synchronization DM, which is connected to schema 0.0.0.1, look like this:

IFW_SYNC_ROUTER_QUEUE
{
 CustCreate
 ServiceLogin
 CustDelete
}
  
IFW_SYNC_QUEUE_1     # queue on local database schema
{
  0.0.0.1
}
0.0.0.2.IFW_SYNC_QUEUE_2     # queue on remote database schema
{
  0.0.0.2
}
0.0.0.3.IFW_SYNC_QUEUE_3     # queue on remote database schema
{
  0.0.0.3
}
  

Note:

In the preceding example, the queue that connects to the Pipeline Manager instance containing the multischema account router (IFW_SYNC_ROUTER_QUEUE) is on the same database schema as the primary queue (IFW_SYNC_QUEUE_1).

The multischema account router is interested in only CustCreate, ServiceLogin, and CustDelete events. However, you can alternatively specify ALL to have all events sent to the router.

Any ifw_sync_queuenames file on a secondary installation machine needs to include entries for only local queues. For example, the entry in the ifw_sync_queuenames file of a secondary Account Synchronization DM connected to schema 0.0.0.2 looks like this:

IFW_SYNC_QUEUE_2     # queue on local database schema
{
  0.0.0.2
}

Configuring the Account Synchronization DM

During installation, the Account Synchronization DM installer generates a pin.conf configuration file that specifies how to connect to your BRM database and database queue and that contains other configuration settings. 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 Account Synchronization DM, verify that the file contains accurate information for connecting to your BRM database and database queue.

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

To configure the Account Synchronization DM:

Note:

Do this for each instance of Account Synchronization DM.
  1. Open the (BRM_Home/sys/dm_ifw_sync/pin.conf) file in a text file.

  2. Verify that the plugin_name entry specifies the path and file name of the correct shared library file:

    -dm plugin_name path/name
      
    

    where name is one of the following:

    • libplugin_ifw_syncdatabase_version.so for Solaris, Linux, and HP-UX IA64

    • libplugin_ifw_syncdatabase_version.a for AIX

    database_version is the version number of your Oracle database.

  3. Verify that the queue_map_file entry specifies the path and file that maps the database queues to the events they are to receive.

    For example:

    - dm_ifw_sync queue_map_file ./ifw_sync_queuenames
      
    

    For more information, see "Mapping Business Events to Database Queues".

  4. Verify that the sm_database entry specifies the alias name of the queuing database to which the Account Synchronization DM connects.

    The value of this entry should be the TNSNAMES.ORA alias, which can be found in the Oracle_Home/network/admin/tnsnames.ora file:

    - dm_ifw_sync sm_database alias_name
      
    
  5. Verify that the sm_id entry specifies the database schema user name that the Account Synchronization DM uses to log in to the queuing database schema:

    - dm_ifw_sync sm_id user_name
      
    
  6. Verify that the sm_pw entry specifies the password for the user specified in the sm_id entry:

    - dm_ifw_sync sm_pw password
      
    
  7. (Optional) You can also edit the entries in Table 22-2:

    Table 22-2 Entries That Are Editable

    Entry Name Description

    connect_retries

    Specifies the number of times that the Account Synchronization DM attempts to connect to the database queue.

    retry_interval

    Specifies the length of time, in seconds, that the Account Synchronization DM waits before attempting to reconnect to the database queue.


    For more information, see "Configuring Account Synchronization DM Database Connection Attempts".

    For other entries you can edit, see the comments in the pin.conf file.

  8. Save and close the file.

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:

  1. Open the registry file.

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

    Important:

    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 section of the registry file that specifies how the Account Synchronization 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.

  3. 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. For more information, see "About Controlling the Business Event Backlog".

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:

  1. Open the registry file.

  2. 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 as 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, after processing all events, this entry is reset to False. To use this feature, you must 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.

      Important:

      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.

      Some entries can be used in a semaphore to update the processing thresholds. If these semaphores contain an error, the pipeline is deactivated and you must reactivate it. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  3. 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 by 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. This is determined by the CheckInterval registry entry. For example, if CheckInterval is set to 180 seconds, the semaphore update becomes effective after 180 seconds have elapsed.

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. (For more information, see the description of how Pipeline Manager assigns delayed events to items in BRM Configuring Pipeline Rating and Discounting.)

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. For more information, see the description of creating custom bill items in BRM Configuring and Running Billing.

Turning On Object Auditing

After installing Account Synchronization Manager, you must enable BRM to audit GSM objects. Auditing objects creates a history of certain information, such as phone numbers and logins, so that BRM can track changes.

For a list of default objects, see "Required Objects to Be Audited".

The object_auditing.pl script invokes the pin_history_on utility to load the file containing the objects to audit and turn on object auditing. It then creates the audit table indexes in the BRM database.

Caution:

  • When installing wireless managers such as Account Synchronization Manager or GSM Manager, you must install all managers before running this script. If you run this script before installing a wireless manager, your installation will fail.

  • If you use a multischema system, do the following:

        1.  Install all wireless managers.

        2.  Install your multischema system.

        3.  Run the object_auditing.pl script.

To enable additions of GSM objects, enter the following command:

perl object_auditing

Note:

The object_auditing.pl script requires a pin.conf configuration file. You can create one (see the description of configuration files in BRM System Administrator's Guide), or you can run the utility from a directory that contains a pin.conf file, such as BRM_Home/sys/dm_ifw_sync.

For more information, see "object_auditing".

You can customize audit table indexes or the list of audited objects by modifying the input files before running the object_auditing.pl script:

  • To customize the list of audited objects, edit the BRM_Home/apps/integrate_sync/pin_history_on_input file.

  • To customize your audit table indexes, edit the BRM_Home/sys/dd/data/create_indexes_audit_tables_oracle.source file.

Required Objects to Be Audited

Pipeline Manager requires certain objects to be audited, which are included in the BRM_Home/apps/integrate_sync/pin_history_on_input file. Table 22-3 lists the default objects and their fields configured in the file:

Table 22-3 Objects Configured in pin_history_on_input

Object Fields Audited by Default

/account

  • PIN_FLD_BRAND_OBJ

  • PIN_FLD_ACCOUNT_NO

  • PIN_FLD_CURRENCY

  • PIN_FLD_RESIDENCE_FLAG

  • PIN_FLD_PRODUCTS.PIN_FLD_USAGE_END_T

  • PIN_FLD_PRODUCTS.PIN_FLD_USAGE_START_T

/profile/acct_extrating

  • PIN_FLD_DATA_ARRAY.PIN_FLD_NAME

  • PIN_FLD_DATA_ARRAY.PIN_FLD_VALUE

  • PIN_FLD_DATA_ARRAY.PIN_FLD_VALID_FROM

  • PIN_FLD_DATA_ARRAY.PIN_FLD_VALID_TO

/profile/serv_extrating

  • PIN_FLD_DATA_ARRAY.PIN_FLD_NAME

  • PIN_FLD_DATA_ARRAY.PIN_FLD_VALUE

  • PIN_FLD_DATA_ARRAY.PIN_FLD_VALID_FROM

  • PIN_FLD_DATA_ARRAY.PIN_FLD_VALID_TO

/service

  • PIN_FLD_AAC_PROMO_CODE

  • PIN_FLD_AAC_VENDOR

  • PIN_FLD_ALIAS_LIST

  • PIN_FLD_ALIAS_LIST.PIN_FLD_NAME

  • PIN_FLD_LOGIN

  • PIN_FLD_STATUS

  • PIN_FLD_AAC_SOURCE

/uniqueness

  • PIN_FLD_LOGIN

  • PIN_FLD_ALIAS_LIST.PIN_FLD_NAME

  • PIN_FLD_SERVICE_OBJ


Configuring Account Synchronization for Multiple Database Schemas

For an overview of how Account Synchronization works in a multischema system, see "About Account Synchronization".

To synchronize accounts in BRM and Pipeline Manager in a multischema system:

  1. Set up your multischema system and create multiple instances of Pipeline Manager for each database schema.

    See "Installing a Multischema System".

  2. Configure each queuing database machine for advanced queuing.

    See "Configuring Database Machines for Advanced Queuing".

  3. Install the Account Synchronization DM on all systems that have the CM installed.

    See "Installing Account Synchronization Manager".

    Note:

    You do not need to perform all the configuration steps for secondary Account Synchronization installations. For example, you do not need to configure the EAI payload, enable event notification, set up service-level items, turn on object auditing, and validate rate plans. These updates are propagated to each database schema by Multidatabase Manager.
  4. (Optional) Create additional database queues.

    See "Creating Additional Account Synchronization Queues".

  5. Grant execute permission for acct_sync to your queuing database schemas so that they can forward events to queues in other schemas when necessary.

    See "Granting Execute Permission for acct_sync".

  6. Map each instance of the DAT_Listener module to its corresponding database queue.

    See "Configuring the DAT_Listener Module".

  7. Map the business events to each database queue in the ifw_sync_queuenames files.

    See "Mapping Business Events to Database Queues".

  8. Edit the configuration file (pin.conf) for each instance of the Account Synchronization DM.

    See "Configuring the Account Synchronization DM".

  9. In the registry section for the DAT_AccountBatch module, add the UseAsRouter entry and set it to True, as in this example:

    CustomerData
        {
        ModuleName = DAT_AccountBatch
        Module
            {
            IntegrateConnection = ifw.DataPool.Login
            InfranetConnection  = ifw.DataPool.LoginInfranet
            LogEvents           = True
            LoadLogins          = True
            Listener            = ifw.DataPool.Listener
            Connections         = 10
            Threads             = 10
            UseAsRouter         = True 
            }
        }
      
    

    For more information on this parameter, see the description of the DAT_AccountBatch module in BRM Configuring Pipeline Rating and Discounting.

  10. In the registry section for the FCT_AccountRouter module, map each BRM database schema identifier to an output stream, as in this example:

    Note:

    You can use any names for the output streams.
    AccountRouter
        {
        ModuleName = FCT_AccountRouter
        Module
            {
            Active            = True
            DataModule        = ifw.DataPool.CustomerData
            Streams
            {
            1 = PinOutputStream1 
            2 = PinOutputStream2 
            3 = PinOutputStream3 
            4 = PinOutputStream4 
            5 = PinOutputStream5 
            }
          }
        }
      
    

    For more information on this parameter, see the description of the FCT_AccountRouter module in BRM Configuring Pipeline Rating and Discounting.

  11. Configure the registry of each Pipeline Manager instance to read accounts from its associated database schema.

    For example, Pipeline Manager 1 connects to database schema 1, Pipeline Manager 2 connects to database schema 2, and so on.

Starting and Stopping the Account Synchronization DM

To start the Account Synchronization DM, enter the following command at the prompt for Oracle AQ:

pin_ctl start dm_ifw_sync
  

To stop the Account Synchronization DM, enter the following command at the prompt for Oracle AQ:

pin_ctl stop dm_ifw_sync

Monitoring and Maintaining the Account Synchronization Queue

This section provides information and guidelines to help you manage your Account Synchronization queues.

The main administrative tasks for database queues are the following:

Creating Additional Queues

You must create additional queues in the following situations:

  • You add a new instance of Pipeline Manager to your system.

  • You add a BRM database schema to your system.

To create additional queues in an existing system:

  1. Stop the Account Synchronization DM.

    See "Starting and Stopping the Account Synchronization DM".

  2. If necessary, configure the Oracle database for Account Synchronization.

    See "Configuring Database Machines for Advanced Queuing".

  3. If you are creating your queue in a new database schema, grant execute permission for its acct_sync package to your other queuing database schemas so they can forward events to the new database queue.

    See "Granting Execute Permission for acct_sync".

  4. Create the new database queue by using pin_ifw_sync_oracle.

    See "Creating Additional Account Synchronization Queues".

  5. Specify which events the Account Synchronization DM sends to the new queue.

    See "Mapping Business Events to Database Queues".

  6. Connect the new queue to its corresponding DAT_Listener module.

    See "Configuring the DAT_Listener Module".

  7. Restart the Account Synchronization DM.

    See "Starting and Stopping the Account Synchronization DM".

Generating Queue Reports

You can monitor the events in your database queue by running the pin_ifw_sync_oracle utility.

Important:

To avoid system errors, do not run Pipeline Manager while running pin_ifw_sync_oracle.

pin_ifw_sync_oracle creates the following reports:

  • A summary report that lists the number of events set to the READY and PROCESSED states.

  • A detailed report that lists each event's ID, state, queuing time, and dequeuing time.

Generating Oracle AQ Reports

To run a summary report for Oracle AQ, enter the following command:

pin_ifw_sync_oracle.pl report -r summary [-q queue_name] -l user_name/password@database_alias
  

where:

  • queue_name specifies the queue name.

  • user_name specifies the user name for the database schema.

  • password specifies the password for the specified user name.

  • database_alias specifies the BRM database alias of the database schema.

To run a detailed report for Oracle AQ, enter the following command:

pin_ifw_sync_oracle.pl report -r detail [-q queue_name] -l user_name/password@database_alias
  

where:

  • queue_name specifies the queue name.

  • user_name specifies the user name for the database schema.

  • password specifies the password for the specified user name.

  • database_alias specifies the BRM database alias of the database schema.

For information, see "pin_ifw_sync_oracle".

Dropping the Queue and Queue Tables

To drop the queue and its queue tables, enter the following command:

Important:

To avoid system errors, do not run Pipeline Manager while running pin_ifw_sync_oracle.
pin_ifw_sync_oracle.pl drop [-q queue_name]
  

where queue_name is dropped from the database.

If the database contains no other queues for Account Synchronization, the utility also removes the Account Synchronization package, which contains stored procedures for queuing, dequeuing, and purging events.

For more information, see "pin_ifw_sync_oracle".

Configuring the Queue Location

By default, the pin_ifw_sync_oracle utility creates Oracle database queues in the tablespace you specified when you installed Account Synchronization Manager. To use a different tablespace, see one of the following:

Specifying Default Storage Settings in the create_ifw_sync_queue.conf File

You can specify the default storage settings by using the create_ifw_sync_queue.conf file. All database queues that you create use the default settings unless you override them with the pin_ifw_sync_oracle utility.

To specify your default storage settings:

  1. Open the BRM_Home/apps/pin_ifw_sync/create_ifw_sync_queue.conf file in a text editor.

  2. Specify the target tablespace and queue size by editing the storage_clause parameter:

    Tip:

    For production systems, create your queue in its own, separate tablespace to improve processing performance.
    $storage_clause = "tablespace PIN00 initrans 5 storage (initial 200k next 200k maxextents unlimited pctincrease 0 )";
      
    
  3. Save and close the file.

Specifying Storage Settings by Using the pin_ifw_sync_oracle Utility

You can specify a queue's storage settings by using the pin_ifw_sync_oracle utility with the -s parameter. This option overrides the storage settings in the create_ifw_sync_queue.conf file.

important:

To avoid system errors, do not run Pipeline Manager while running the pin_ifw_sync_oracle utility.

To specify storage settings by using the pin_ifw_sync_oracle utility, enter the following command:

su - pin
pin_ifw_sync_oracle.pl create [-q queue_name -t queue_table] -s storage_clause
  

where:

  • queue_name specifies the queue name.

  • queue_table specifies the queue table name.

  • storage_clause specifies the queue's storage parameters.

For more information, see "pin_ifw_sync_oracle".

Tip:

For production systems, create your queue in its own, separate tablespace to improve processing performance.

Configuring How Often Processed Events Are Removed from the Queue

The Oracle queue monitor process (QMn) removes from the queue any event that has been in the PROCESSED state for a specified amount of time. You specified a default retention time when you installed Account Synchronization Manager. To use a different retention time, see one of the following:

Setting Default Retention Time in the create_ifw_sync_queue.conf File

You can set the default retention time in the create_ifw_sync_queue.conf file. All database queues that you create use this default setting unless you override it with the pin_ifw_sync_oracle utility.

To set the default retention time in the create_ifw_sync_queue.conf file:

  1. Open the BRM_Home/apps/pin_ifw_sync/create_ifw_sync_queue.conf file in a text editor.

  2. Set the retention_time parameter to the amount of time, in seconds, that you want to store processed events in the database queue:

    Note:

    For production systems, set the retention time to 0 to optimize your processing performance.
    retention_time = retention_time;
      
    
  3. Save and close the file.

Setting Retention Times by Using the pin_ifw_sync_oracle Utility

You can specify a queue's retention time by using the pin_ifw_sync_oracle utility with the -r parameter. This option overrides the retention time setting in the create_ifw_sync_queue.conf file.

Important:

To avoid system errors, do not run Pipeline Manager while running pin_ifw_sync_oracle.

To set the retention time by using the pin_ifw_sync_oracle utility:

su - pin
pin_ifw_sync_oracle.pl create [-q queue_name -t queue_table] -r retention_time
  

where:

  • queue_name specifies the queue name.

  • queue_table specifies the queue table name.

  • retention_time specifies the queue's retention time, in seconds.

For more information, see "pin_ifw_sync_oracle".

Tip:

For production systems, set the retention time to 0 to optimize your processing performance.

Configuring Account Synchronization DM Database Connection Attempts

You can configure how often the Account Synchronization DM attempts to connect to the database schema that contains the Account Synchronization queue.

To configure connection attempts:

  1. Open the BRM_Home/sys/dm_ifw_sync/pin.conf) file in a text editor.

  2. Specify the number of times the Account Synchronization DM should try to connect to the Oracle database server by editing the connect_retries entry.

    The default is 1.

    -dm_ifw_sync connect_retries number_of_retries
      
    
  3. Specify the interval, in seconds, between each reconnection attempt by editing the retry_interval entry.

    The default is 0.

    -dm_ifw_sync retry_interval interval
      
    
  4. Save and close the file.

  5. Stop and restart the Account Synchronization DM.

    See "Starting and Stopping the Account Synchronization DM".

Disconnecting and Reconnecting the Account Synchronization DM to the Queue

You can prevent the Account Synchronization DM from enqueuing business events when you tune or shut down the queuing database schema by using the pin_ctl utility. See BRM System Administrator's Guide.

To disconnect from the queue, enter the following command:

pin_ctl stop dm_ifw_sync
  

To reconnect to the database queue and begin enqueuing business events, enter the following command:

pin_ctl start dm_ifw_sync
  

For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Disconnecting and Reconnecting DAT_Listener to the Queue

You can keep Pipeline Manager online when you tune or shut down the queuing database schema by disconnecting the DAT_Listener module from the queue. For more information, see "About Disconnecting the Account Synchronization DM from the Queue".

To disconnect the module from the database queue, enter the following semaphore file entry:

ifw.DataPool.Listener.Module.Disconnect{} 
  

To reconnect the DAT_Listener module to the database queue, enter the following semaphore file entry:

ifw.DataPool.Listener.Module.Connect{}
  

For more information about the semaphore entries, see the description of the DAT_Listener module in BRM Configuring Pipeline Rating and Discounting.

Troubleshooting Account Synchronization

If an error occurs during an account synchronization operation, check the account synchronization log file (BRM_Home/sys/dm_ifw_sync/dm_ifw_sync.pinlog) for error codes. For a list of standard errors and codes, see the description of BRM error codes in BRM System Administrator's Guide.

Database Queue Creation Error

To install the Account Synchronization DM and create database queues, the pin user must have Oracle AQ privileges. If pin does not have privileges, you receive the following error when you attempt to install the Account Synchronization DM or create queues with the pin_ifw_sync_oracle utility:

PLS-00201 identifier 'SYS.DBMS_AQ' must be declared
  

To fix this error:

  1. Using SQL*Plus, log in to your database as the SYS user and grant advanced queuing privileges to user pin:

    % sqlplus sys/password@databaseAlias
    SQL> grant execute on dbms_aq to pin;
      
    Grant succeeded.
      
    SQL> grant execute on dbms_aqadm to pin;
      
    Grant succeeded.
      
    SQL> grant execute on dbms_lock to pin;
      
    Grant succeeded.  
      
    
  2. Reinstall the Account Synchronization DM or create your queue by running the pin_ifw_sync_oracle utility manually.

    See "Creating Additional Account Synchronization Queues".

Interleaved Processing Errors

This section describes interleaved processing errors and their solutions.

Missing Registry Entries

If you enable interleaved event processing in DAT_Listener, and you specify the event and CDR processing time entries (MaxEventProcessTime and MaxCDRProcessTime), you must also specify the entries that set the number of event thresholds (MaxNumEvents and MinNumEvents). If you do not do this, DAT_Listener throws a critical error (ERR_REG_VALUE_INVALID) during startup. However, if you update the registry by using a semaphore and the required entries are not specified, DAT_Listener throws a warning and disregards the semaphore update.

Semaphore Entry Errors

When an interleaving semaphore entry contains an error, the pipelines are deactivated.

The following interleaving semaphore errors cause the pipelines to be deactivated:

  • The values for MinNumEvents and MaxNumEvents are not numbers.

  • MinNumEvents is less than MaxNumEvents.

  • The values for MaxEventProcessTime and MaxCDRProcessTime are not numbers.

  • CheckInterval is not a number.

To reactivate the pipelines, use the Active semaphore. For example:

ifw.Pipelines.PRE_PROCESS.Active=TRUE
ifw.Pipelines.PRE_RECYCLE.Active=TRUE
ifw.Pipelines.ALL_RATE.Active=TRUE
  

After the pipelines are reactivated, reissue the interleaving semaphore using the correct values.

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 Account Synchronization DM for publishing to Pipeline Manager. You do this by customizing the Account Synchronization policy opcode, PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT. See BRM Developer's Reference.

Note:

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

You might want to 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. For more information, see the description of the PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT policy opcode in BRM Developer's Reference.

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

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

    See "Configuring Event Notification for Account Synchronization".

  2. Use PCM_OP_IFW_SYNC_PUBLISH_EVENT to process the BRM events that make up the business event.

    See "Processing BRM Events That Make Up Account Synchronization Business Events".

  3. 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 Make Up Account Synchronization Business Events".

Processing BRM Events That Make Up Account Synchronization Business Events

PCM_OP_IFW_SYNC_PUBLISH_EVENT passes BRM events that make up Account Synchronization 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. See "Configuring Event Notification for Account Synchronization".

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 Make Up Account Synchronization 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 that you do not want to include in published business events for various business or performance reasons.

    Important:

    • Do not filter out balance impact fields based on the resource ID. If you do, you might 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 might use this method, for example, when a customer purchases a service that includes 60 free minutes per month and cancels the service before the end of the month. If the customer has used all 60 minutes, but you prorate the free minutes, 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 22-4:

Table 22-4 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 when you want to specify a negative balance for resources, 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 product is purchased and when billing is run. For product purchase, Pipeline Manager must be notified so it can update the in-memory account data. However, for billing, Pipeline Manager performs the account balance update 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 resource 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 dynamically update the rating basis.

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

Manually Configuring Object Auditing

To enable BRM to audit GSM objects, run the object_auditing.pl script. For more information, see "Turning On Object Auditing".

The object_auditing.pl script performs a series of steps that can also be performed manually. This section describes these manual steps.

To manually configure object auditing:

Running the pin_history_on Utility

Caution:

  • When installing wireless managers such as Account Synchronization Manager or GSM Manager, you must install all managers before running this utility. If you run this utility before installing a wireless manager, your installation will fail.

  • If you are using a multischema system, do the following:

        1.  Install all wireless managers.

        2.  Install your multischema system.

        3.  Run the pin_history_on utility.

Important:

  • The pin_history_on utility requires a pin.conf configuration file. You can create one (see the description of creating configuration files in BRM System Administrator's Guide), or you can run the script from a directory that contains a pin.conf file, such as BRM_Home/sys/dm_ifw_sync.

  • Before running this utility, you must manually modify entries in the Oracle DM configuration file to give the DM write permission so that the objects in the input file can be written to the database. After running the utility, you restore the entries in the configuration file to their original values.

To run the pin_history_on utility:

  1. Open the BRM_Home/sys/dm_oracle/pin.conf file in a text editor.

  2. Note the value of the following entries:

    - dm dd_write_enable_fields 
    - dm dd_write_enable_objects 
    - dm dd_write_enable_portal_objects 
    - dm dd_mark_as_portal 
      
    
  3. Set the values of the following entries to 1.

    - dm dd_write_enable_fields 1
    - dm dd_write_enable_objects 1
    - dm dd_write_enable_portal_objects 1
    - dm dd_mark_as_portal 1
    

    Note:

    If an entry is not in the file, add it.
  4. Save and close the file.

  5. Stop and restart the Oracle DM.

  6. Run the pin_history_on utility:

    pin_history_on pin_history_on_input
    

    Note:

    If you run the utility from another directory, include the path to the pin_history_on utility in the command line. For example:
    pin_history_on BRM_Home/bin/pin_history_on_input
    

    For more information, see "pin_history_on".

  7. Open the BRM_Home/sys/dm_oracle/pin.conf file in a text editor.

  8. Restore the following entries to their original values (the values they had before you modified them):

    - dm dd_write_enable_fields 
    - dm dd_write_enable_objects 
    - dm dd_write_enable_portal_objects 
    - dm dd_mark_as_portal 
      
    
  9. Save and close the file.

  10. Stop and restart the Oracle DM.

Creating Audit Table Indexes

After running the pin_history_on utility, you must create indexes for the new audit tables.

The Account Synchronization installation installs a file (create_indexes_audit_tables_oracle.source) that specifies the necessary indexes on the audit tables.

  1. Open the BRM_Home/sys/dd/data/create_indexes_audit_tables_oracle.source file in a text editor.

  2. Set the $PIN_CONF_TBLSPACEX1 entry to pinx00.

    Note:

    This entry must have the same value as the variable $MAIN_DB{'indexes_group'} configured in the BRM_Home/setup/pin_setup.values file. The default value of this entry is pinx00.
  3. Set the $PIN_CONF_STORAGE_MED entry to the following:

    storage (initial 200k next 200k maxextents unlimited pctincrease 0)
      
    
  4. Save and close the file.

  5. Create the audit table indexes in SQL*Plus by running the following command:

    sqlplus user/password@database_Alias @filepath/create_indexes_audit_tables_oracle.source