Configuring Suspense and Recycle on the BRM Server

3 Configuring Suspense and Recycle on the BRM Server

This document explains how to set up Oracle Communications Billing and Revenue Management (BRM) Suspense Manager.

Topics in this document:

Connecting Suspended Event (SE) Loader to the BRM Database

Suspended Event (SE) Loader moves suspended records from Offline Mediation Controller to /suspended_usage objects the BRM database. To connect to the BRM database, SE Loader uses the pin_rel utility. Therefore, you need to add the suspense configuration entries to the pin_rel utility Infranet.properties file. To do so, run the following commands:

% cd BRM_home/apps/pin_rel
% cat suspense_Infranet.properties Infranet.properties

Configuring SE Loader for the pin_recycle Utility

The pin_recycle utility requires SE Loader configuration:

Add a separate instance of SE Loader to each instance of Offline Mediation Controller.
Create a new BRM_home/apps/pin_rel/suspense directory by copying the contents of BRM_home/apps/pin_rel/gsm/tel to BRM_home/apps/pin_rel/suspense. BRM_home is the directory where you installed BRM components.
Confirm that these files are in the BRM_home/apps/pin_rel/suspense directory:
- pin.conf
- SampleRelHandler_config.values
- SampleRelHandler.pl
Add these entries to the BRM_home/apps/pin_rel/suspense/SampleRelHandler_config.values file:
```
$FILETYPE = "*.out.bc";
$HANDLER_DIR = "BRM_home/apps/pin_rel/suspense";#
```

Edit the BRM_home/apps/batch_controller/Infranet.properties file, adding SUSPENSE and RECYCLE_ROLLBACK entries to batch.random.events:

batch.random.events     TEL,SMS,FAX,DATA,GPRS,SUSPENSE,RECYCLE_ROLLBACK

Add these parameters to the new entries:

#for SUSPENSE events:
SUSPENSE.name                    SUSPENSE Usage
SUSPENSE.handlers                suspHandler
SUSPENSE.file.location           Offline Mediation Controller_output
SUSPENSE.file.pattern            suspense_ *.out

suspHandler.name                 suspHandler
suspHandler.max.at.highload.time 1
suspHandler.max.at.lowload.time  1
suspHandler.start.string           BRM_home/apps/pin_rel/suspense /SampleRelHandler.pl

#For RECYCLE_ROLLBACK events:
RECYCLE_ROLLBACK.name            RECYCLE_ROLLBACK Usage
RECYCLE_ROLLBACK.handlers        recycleRollbackHandler
RECYCLE_ROLLBACK.file.location   Offline Mediation Controller_output
RECYCLE_ROLLBACK.file.pattern    testDB*.err

recycleRollbackHandler.name      recycleRollbackHandler
recycleRollbackHandler.max.at.highload.time  1
recycleRollbackHandler.max.at.lowload.time   1
recycleRollbackHandler.start.string      BRM_home/apps/pin_rel/recycle/SampleRelHandler.pl

Confirm that these BRM_home/apps/pin_rel/Infranet.properties file entries are set to false:
```
infranet.rel.validate_dbnumber = false
infranet.rel.validate_indexes = false
```
Note:

The SE Loader architecture makes obsolete the database consistency checks and number validation controlled by these entries.
Create a new BRM_home/apps/pin_rel/recycle directory by copying the contents of BRM_home/apps/pin_rel/gsm/tel to BRM_home/apps/pin_rel/recycle.
Add these entries to the BRM_home/apps/pin_rel/recycle/SampleRelHandler_config.values file:
```
$FILETYPE = "*.err.bc";
$HANDLER_DIR = "BRM_home/apps/pin_rel/recycle";#
```

Connecting Suspended Batch (SB) Loader to the BRM Database

Suspended Batch (SB) Loader moves suspended batch files from Offline Mediation Controller to /suspended_batch objects in the BRM database. To connect to the BRM database, SB Loader uses the load_suspended_batch_info.pl script This script is usually set up to run automatically, but can also be run manually as needed.

Configuring Event Notification for Suspense Manager

When suspended event records are recycled or written off, Suspense Manager uses event notification to call opcodes that perform the appropriate follow-up operations.

Although any subclass of the /event storable class can be used to trigger event notification (see "About Notification Events" in BRM Developer's Guide), Suspense Manager generates the following nonpersistent events specifically to use for event notification:

/event/notification/suspense/recycle: By default, when this event occurs, the EAI framework publishing opcode is called.
/event/notification/suspense/writeoff: By default, when this event occurs, PCM_OP_PROCESS_AUDIT_CREATE_WRITEOFF_SUMMARY is called.
/event/notification/suspense/delete: By default, when this event occurs, no opcode is called. To enable this event to trigger an opcode call, see "Editing The Event Notification List" in BRM Developer's Guide.
/event/notification/suspense/edit: By default, when this event occurs, no opcode is called. To enable this event to trigger an opcode call, see "Editing The Event Notification List" in BRM Developer's Guide.

Before you can use Suspense Manager, you must configure the event notification feature as follows:

If your system has multiple configuration files for event notification, merge them. See "Merging Event Notification Lists" in BRM Developer's Guide.
Ensure that the merged file includes entries for these events:
- (For Revenue Assurance Manager only) From BRM_home/sys/data/config/pin_notify_ra:
  
  /event/notification/suspense/writeoff
- From BRM_home/sys/data/config/pin_notify_ifw_sync:
  
  /event/notification/suspense/recycle
(Optional) Add entries for these events to your final event notification list:
- /event/notification/suspense/edit
- /event/notification/suspense/delete
  
  Note:
  
  These events are not in a default event notification configuration file. You must manually add them to your final event notification list. See "Editing the Event Notification List" in BRM Developer's Guide.
(Optional) If necessary to accommodate your business needs, add, modify, or delete entries in your final event notification list. See "Editing the Event Notification List" in BRM Developer's Guide.
(Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger. See "Triggering Custom Operations" in BRM Developer's Guide.
Load your final event notification list into the BRM database. See "Loading the Event Notification List" in BRM Developer's Guide.

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

Configuring the Oracle AQ Queue to Send Data to Offline Mediation Controller

Suspense Manager Center and the pin_recycle utility both use the Oracle AQ queue to send recycled records and batches to the Offline Mediation Controller Recycle AQ Job CC node.

The BRM installer automatically creates a default queue in a specified database schema. To configure the queue to send data to Offline Mediation Controller:

If your system requires multiple queues, create additional queues by manually running the pin_ifw_sync_oracle utility.

See the discussion about creating additional account synchronization queues in BRM Installation Guide.
The default BRM database number for your Oracle DM is 0.0.0.1. If you change your database number, you must change the value of the DB attribute in the Oracle DM publisher definition. See the information about specifying the Oracle DM database number in BRM Installation Guide.]
You configure which events the Oracle 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. See the information about mapping business events to database queues in BRM Installation Guide.
You must modify the CM pin.conf file to enable the EAI framework to notify the Oracle DM when specific events occur. You should also verify that the pointer to the Oracle 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.

See the discussion about configuring the CM for account synchronization in BRM Installation Guide.

Configuring the Payload Definition File for Suspense Manager

If you use a different Synchronization Queue DM database number, you must change the value of the publisher database in the payload configuration file.

In a text editor, open the payload configuration file in the BRM_home/sys/eai_js directory (payloadconfig_crm_sync.xml, or the merged file if you merged payload configuration files), where BRM_home is the directory in which BRM is installed.
Search for the following entry:
```
RecycleRequest
```

Add or modify the entries for suspended events.

For example:

<!-- For Suspended Events -->
<RecycleRequest Source="EVENT"
Tag="RecycleRequest"
StartEvent="/event/notification/suspense/recycle" >
<Attribute Tag="Version" Value="1.0" />
<Field PinFld="PIN_FLD_ACCOUNT_OBJ" Tag="AccountObj"/>
<SubElement Name="JobActions"
OnEvent="/event/notification/suspense/recycle" />
</RecycleRequest>

Search for the following entry:
```
ResubmitBatchRequest
```

Add or modify the entries for suspended batch.

For example:

<!-- For Suspended Batch -->
<ResubmitBatchRequest Source="EVENT"
Tag="ResubmitBatchRequest"
StartEvent="/event/notification/suspense/batch_resubmit" >
<Attribute Tag="Version" Value="1.0" />
<Field PinFld="PIN_FLD_ACCOUNT_OBJ" Tag="AccountObj"/>
<SubElement Name="JobActions"
OnEvent="/event/notification/suspense/batch_resubmit" />
</ResubmitBatchRequest>

Add or modify the entries for the event sub-element.

For example:

<!-- Action Obj -->
<JobActions Source="EVENT" PinFld="PIN_FLD_ACTIONS"
DataFrom="PIN_FLD_ACTIONS" Tag="Actions" >
<Field PinFld="PIN_FLD_ACTION_OBJ" Tag="ActionObj" />
</JobActions>

Save and close the file.

Integrating Event Record Field Mapping

To process records in Offline Mediation Controller, you need to map record field names to numbers. To do so, you edit the edr_field_mapping.xml file and load it into the BRM database.

To define and load field mappings:

Open the edr_field_mapping.xml file in the BRM_home/sys/data/config/ directory.
Search for the following line:
```
<edr_field_mapping name="Name">
  
```
where, Name is the version number of the mapping.
Add or update an id field entry, using the following syntax:
- The id field must contain numbers and periods.
  
  The parent block field container must end with a .b value. The child id field must be sequentially numbered and prefixed with the parent id block field's value, without the .b value.
- A type field, which contains the numbers 1, 2, 4, 8, or 32.
  
  where:
  - 1 is used for string data types.
  - 2 is used for integer data types.
  - 4 is used for date data types.
  - 8 is used for decimal data types.
  - 32 is used for block data types.
For example:
```
<f id="1.5.b" name="DETAIL.ASS_DUMMY_EXT" type="32"/>
<f id="1.5.0.1" name="DETAIL.ASS_DUMMY_EXT.RECORD_TYPE" type="1"/>
<f id="1.5.1.2" name=DETAIL.ASS_DUMMY_EXT.RECORD_NUMBER" type="2"/>
  
```
Note:

Before new entries are loaded in the database, all existing entries that contain the same version number as the new entries are deleted. To prevent overwriting of existing entries when the edr_field_mapping.xml file is loaded into the database, configure the name attribute to increment the version number to the next number.
Save and close the file.
Go to the BRM_home/sys/data/config/ directory.
Run the following command, which loads the event record field mapping file into the BRM database:
```
load_edr_field_mapping XML_file
  
```
where XML_file is the name of the XML file that contains the configuration data.

See "load_edr_field_mapping" for more information.

Configuring Debugging

Suspense Management Center provides the following optional ways for capturing and displaying debugging information:

The SuspenseManagementCenter_opcodes.log log file captures all opcode input and output flists used by Suspense Management Center.
The javapcm.log file contains detailed debugging information. By default, the logging level is set to 0, the lowest level. The highest level is 3. You must set the error buffer to true to enable javapcm logging.
The Dloglevel entry creates a console window for the Suspense Management Center that displays error messages and debugging information.

Set up Java PCM Logging by adding these entries to the Infranet.properties file (in the BRM_home/Program Files/Portal Software/SuspenseManagementCenter/lib directory):
```
infranet.log.level=3
infranet.log.logallebuf=true
infranet.log.opcodes.enabled=true
infranet.log.opcodes.file=SuspenseManagementCenter_opcodes.log
```
Set up Suspense Management Center console logging by opening the RunSM.bat file (in the BRM_home\Program Files\Portal Software\SuspenseManagementCenter\lib directory), and changing the javaw entry to java, and add this parameter:
```
java -Dloglevel="ALL".
```

Logging information is now:

Displayed in the Suspense Management Center console window.
Available in these files:
- BRM_home\Program Files\Portal Software\SuspenseManagementCenter\lib\javapcm.log
- BRM_home\Program Files\Portal Software\SuspenseManagementCenter\lib\SuspenseManagementCenter_opcodes.log

Setting Up pin_recycle to Run Periodically

Some BRM functionality temporarily interrupts and then restarts rating. These programs and features use pin_recycle to recycle records when the interruption is over. These features, such as account migration, temporarily stop rating by suspending calls that come in during the interruption. As these call records arrive, they are appended with a recycle key. When the interruption is over, you use pin_recycle to rate all the stored calls that contain that recycle key. You can further configure this feature by using any number of different recycle keys to control when suspended records get recycled.

The -k recycle key option directs pin_recycle to search for all records that contain a specific recycle key string and a status of suspended, and queues them for rating. The BRM feature that suspends records determines which records contain the same recycle key and need to be recycled together. This gives pin_recycle the flexibility to selectively restrict recycling to just the records with specific characteristics.

For example, the account migration feature moves groups of accounts across databases, and must temporarily stop rating for each group of accounts while they are being moved. Account migration uses internal job IDs to keep track of the accounts being moved, and it also uses these job IDs in the recycle keys for suspended records associated with those same accounts.

You need to run pin_recycle periodically both to queue the temporarily stored records for rating, and to delete them. The cron command is the typical way to do this, although you can run pin_recycle like any other BRM command-line utility. This section explains how to set up cron command to run pin_recycle.

You need to add two pin_recycle entries to the cron command. One to search for and recycle records, and the other to delete them after they are recycled. See "pin_recycle" for the syntax.

To run pin_recycle periodically, add entries like the following. The following crontab entry runs pin_recycle at 1:00 a.m. daily, and queues records with a recycle key of Trigger_Billing for rating:

0 1 * * * BRM_home/bin/pin_recycle -k Trigger_Billing &

To remove records from the BRM database, add an entry like the following. The following crontab entry runs pin_recycle at 1:00 a.m. daily, and deletes records with a recycle key of Trigger_Billing:

0 1 * * * BRM_home/bin/pin_recycle -k Trigger_Billing -d &