Installing and Configuring Account Synchronization

15 Installing and Configuring Account Synchronization

Learn how to install and configure Oracle Communications Billing and Revenue Management (BRM) Account Synchronization Manager.

Topics in this document:

Installing and Configuring Account Synchronization

To install Account Synchronization:

Configure your database machines for advanced queuing.

See "Configuring Your Database for Advanced Queuing".
Install Account Synchronization Manager.

See "Installing Individual BRM Components".

Note:

Account Synchronization Manager is dependent on the BRM Connection Manager (CM) and must be installed on all hosts on which the CM is run.

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), Account Synchronization Manager must be installed on the same host where the existing EAI server is installed.
Create additional Account Synchronization queues.

See "Creating Additional Queues for Multischema BRM Systems".
If your system contains queues in multiple database schemas, grant execute permission for acct_sync.

See "Granting Execute Permission for acct_sync".
Configure the EAI payload for Account Synchronization.

See "Configuring the EAI Payload for Account Synchronization".
Enable event notification.

See "Configuring Event Notification for Account Synchronization".
Configure Account Synchronization.

See "Configuring Account Synchronization".
Enable BRM to audit GSM (Global System for Mobile Communication) objects.

See "Turning On Object Auditing".

Configuring Your Database for Advanced Queuing

BRM uses Oracle Advanced Queuing (AQ) database queues to do the following:

Synchronize its customer data with Elastic Charging Engine (ECE). See "About Synchronizing Account Data between the BRM Database and ECE".
Synchronize its pricing data with external customer relationship management (CRM) applications. See "Understanding the Synchronization Queue Data Manager" in BRM Synchronization Queue Manager.

Before installing BRM, you must configure your database for Oracle AQ.

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

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.
Set the compatible parameter to specify the Oracle database version.

Note:

If you use an entry lower than 12.0, your BRM system fails.
Specify one Oracle Queue Monitor process (QMn) by setting the aq_tm_process parameter to 1.

By default, QMn removes from the queue any processed events that are over an hour old.
Save and close the file.

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.

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

Creating Additional Queues for Multischema BRM Systems

The Account Synchronization installer automatically creates a Notification queue in the specified BRM schema. A Suspense queue and an Acknowledgment queue are created in the specified schema when you run the ECE post-installation script (post_Install.pl).

If you have a multischema BRM system, you must manually create these queues for each secondary BRM schema:

Notification queue (IFW_SYNC_QUEUE)
Suspense queue (ECE_SUSPENSE_QUEUE)
Acknowledgment queue (ECE_ACK_QUEUE)

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

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

For more information, see:
- Configuring the Queue Location
- Configuring How Often Processed Events Are Removed from the Queue
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.
Run the following command to create a Notification queue:
```
pin_ifw_sync_oracle.pl create -l /@database_alias
```
where 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. For more information about the utility's parameters, see "pin_ifw_sync_oracle".

Run the following command to create a Suspense queue:

pin_ifw_sync_oracle.pl create -q ECE_SUSPENSE_QUEUE -t IFW_SYNC_SUS -l /@database_alias

Run the following command to create a Acknowledgment queue:

pin_ifw_sync_oracle.pl create -q ECE_ACK_QUEUE -t ACK_QUEUE_T -l /@database_alias

Run the following command for each queue, which verifies that it was created and it functions properly by attempting to enqueue and dequeue 20 test events:
```
pin_ifw_sync_oracle.pl test -q queue_name -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.

Run the following command for each queue, 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 /@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".

Creating an Acknowledgment Queue for Account Migration Manager

In a system containing Account Migration Manager, an AMM acknowledgment queue pushes AMM-related events. If events are enqueued into an AMM 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:

Open the BRM_home/apps/pin_ifw_sync/create_ifw_sync_queue.conf file in a text editor.
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 AMM acknowledgment queue is configured in schema pin01 and the events from schema pin02 have to be enqueued into that queue:
```
$primary_schema = "pin01"
```
Save and close the file.

To enable access to the schema where the AMM acknowledgment queue resides:

Create a new file_name.sql file.

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 AMM acknowledgment queue name.
queue_table is the database table that contains the AMM 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;

Open SQL *Plus by entering the following command:
```
sqlplus pin@ORACLE_SID
Enter password: password
```
where ORACLE_SID is the BRM database alias.
From the schema where the acknowledgment queue is configured, run the following command:
```
@file_name.sql
```
Run the pin_ifw_sync_oracle utility. See "pin_ifw_sync_oracle" 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:

Log in to a target database schema:
```
% sqlplus target_schema_user_name@database_alias
Enter password: password
```
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.
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:

Log in to the pin2 schema:
```
% sqlplus pin2@database_alias
Enter password: password
```
where:
- password is the password for the pin2 schema user name.
- database_alias is the BRM database alias of the pin2 schema.
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:

If you have another EAI-based publisher, you must do the following:
- Check for conflicts in the EAI payload configuration files.
  
  See "Checking for Conflicts in EAI Payload Configuration Files".
- Specify the default configuration file.
  
  See "Specifying the Default Payload Configuration File".
If your Account Synchronization DM database number is not the default (0.0.9.9). See "Specifying the Account Synchronization DM Database Number".
If you uninstall the Account Synchronization DM. See "Revising the Payload Configuration File When Uninstalling Account Synchronization Manager".

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.

Note:

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:

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.
Find the <PublisherDefs> section.
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">
```
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:

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.
Find the <PublisherDefs> section.

Remove the following publisher definition:

<Publisher DB="database_number" Format="FLIST">

Save and close the file.
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:

If your system has multiple configuration files for event notification, merge them.
Ensure that the merged file includes the entire event notification list in the BRM_home/sys/data/config/pin_notify_ifw_sync file.
(Optional) If you defined new business events for Account Synchronization, you must edit your final event notification list to include all of the BRM events in the new business events.
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:

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".
Map BRM business events to the appropriate database queue by editing the ifw_sync_queuenames file.

See "Mapping Business Events to Database Queues".
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 enable the EAI framework to notify Account Synchronization Manager when specific events occur. To do so, you modify the CM pin.conf file.

Note:

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

To configure the CM for account synchronization:

Open the CM configuration file (BRM_home/sys/cm/pin.conf) in a text editor.
Set the enable_publish entry to 1:
```
- fm_publish enable_publish 1
```
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.
  
  If you change the location of the Account Synchronization DM, you must modify this entry.
  Note:
  
  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).
Save and close the file.
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:

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

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 15-1 shows the syntax for each criteria:

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

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
}

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.

Open the (BRM_home/sys/dm_ifw_sync/pin.conf) file in a text file.
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 and Linux
- libplugin_ifw_syncdatabase_version.a for AIX
database_version is the version number of your Oracle database.
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".
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
```
Verify that the sm_id entry specifies the database schema user name that Account Synchronization Manager uses to log in to the queuing database schema:
```
- dm_ifw_sync sm_id user_name
```

(Optional) You can also edit the entries in Table 15-2.

Table 15-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.
database_request_timeout_duration	Specifies the length of time, in milliseconds, that the Account Synchronization DM waits for a response from the database before timing out.

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.

Save and close the file.

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.

The object_auditing.pl utility 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, 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 use a multischema system, do the following:

1. Install all wireless managers.

2. Install your multischema system.

3. Run the object_auditing.pl utility.

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

perl object_auditing

Note:

The object_auditing.pl utility requires a pin.conf configuration file. You can create one or you can run the utility from a directory that contains a pin.conf file, such as BRM_home/sys/dm_ifw_sync.

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

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.

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 if you add a BRM database schema to your system.

To create additional queues in an existing system:

Stop the Account Synchronization DM.

See "Starting and Stopping the Account Synchronization DM".
If necessary, configure the Oracle database for Account Synchronization.

See "Configuring Your Database for Advanced Queuing".
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".
Create the new database queue by using pin_ifw_sync_oracle.

See "Creating Additional Queues for Multischema BRM Systems".
Specify which events the Account Synchronization DM sends to the new queue.

See "Mapping Business Events to Database Queues".
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.

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 /@database_alias

where:

queue_name specifies the queue 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 /@database_alias

where:

queue_name specifies the queue name.

database_alias specifies the BRM database alias of the database schema.

Dropping the Queue and Queue Tables

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

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.

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:

Open the BRM_home/apps/pin_ifw_sync/create_ifw_sync_queue.conf file in a text editor.
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 )";
```
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.

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.

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:

Open the BRM_home/apps/pin_ifw_sync/create_ifw_sync_queue.conf file in a text editor.
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;
```
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.

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.

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:

Open the BRM_home/sys/dm_ifw_sync/pin.conf) file in a text editor.
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
```
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
```
Specify the length of time, in milliseconds, that the Account Synchronization DM waits for a response from the database before timing out.
The default is 0, which means that the Account Synchronization DM will wait indefinitely for a response from the database.
```
-dm_ifw_sync database_request_timeout_duration duration
```
Save and close the file.
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. For information about the utility's syntax and parameters, see "pin_ctl" in 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.

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:

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

% sqlplus sys@databaseAlias
Enter password: password

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.

Reinstall the Account Synchronization DM or create your queue by running the pin_ifw_sync_oracle utility manually.

See "Creating Additional Queues for Multischema BRM Systems".

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.

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:

Modify the DM configuration file (pin.conf) and run the pin_history_on utility.

See "Running the pin_history_on Utility".
Modify the create_indexes_audit_tables_oracle.source file and create the audit table indexes.

See "Creating Audit Table Indexes".

Running the pin_history_on Utility

Caution:

When installing wireless managers such as Account Synchronization 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.

To run the pin_history_on utility:

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

Note the value of the following entries:

- dm dd_write_enable_fields 
- dm dd_write_enable_objects 
- dm dd_write_enable_BRM_objects 
- dm dd_mark_as_BRM

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_BRM_objects 1
- dm dd_mark_as_BRM 1

Note:

If an entry is not in the file, add it.

Save and close the file.
Stop and restart the Oracle DM.
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
```
Open the BRM_home/sys/dm_oracle/pin.conf file in a text editor.

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_BRM_objects 
- dm dd_mark_as_BRM

Save and close the file.
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.

Open the BRM_home/sys/dd/data/create_indexes_audit_tables_oracle.source file in a text editor.
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.

Set the $PIN_CONF_STORAGE_MED entry to the following:

storage (initial 200k next 200k maxextents unlimited pctincrease 0)

Save and close the file.

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

sqlplus @database_Alias @filepath/create_indexes_audit_tables_oracle.source