Suspending and Recycling Records

4 Suspending and Recycling Records

You configure node chains to suspend and recycle records and batches of records in Oracle Communications Offline Mediation Controller.

Topics in this document:

About Suspending and Recycling Records and Batches

You can suspend and recycle events to correct processing errors. Processing errors can occur when:

There is an issue with a record, such as missing or incorrect fields.
There is a problem with an incoming CDR file due to a bad policy or configuration.
There is an issue in your system configuration, such as it contains the wrong pricing information or the account information is not loaded into the system.

You can suspend and recycle individual records or a batch of records.

Failed records and batches are found during processing in Offline Mediation Controller. They are sent to the BRM server where you can analyze and correct the problems, and then send them back to Offline Mediation Controller to be processed again.

About Suspense and Recycle Node Chains

To suspend and recycle records and batches in Offline Mediation Controller, you create a suspense node chain and a recycle node chain. Figure 4-1 shows the suspense and recycle node chains.

Figure 4-1 Suspense and Recycle Node Chains

Description of "Figure 4-1 Suspense and Recycle Node Chains"

The suspense node chain does the following:

A node, such as an EP node, finds an error in a record or batch.
The node where the error was found sends the record or batch to the NAR CC node.
The NAR CC node reads the record or batch from the suspense directory and prepares the record or batch for further processing.
The NAR CC node sends the record or batch to the Suspense CD node.
The Suspense CD node sends the record or batch to BRM to be processed by BRM Suspense Manager. To do so, the Suspense CD node generates a Create file.

The recycle node chain does the following:

The Recycle Job AQ CC node receives a record or batch from BRM and prepares the record or batch for further processing. To identify the record or batch, the Recycle Job AQ CC node receives the job ID message from the Oracle AQ queue.
The Recycle Job AQ CC node sends the record or batch to the Recycle EP node.
The Recycle EP node uses the job ID message to send the record or batch to the node that reported the original error.
If no errors are found, the record or batch is sent to two nodes:
- The next node in the node chain. In Figure 4-1 this is the ECE DC node.
- The NAR CC node, which sends the record or batch to the Suspense DC node. The Suspense DC node sends the output to BRM to record that the record or batch was processed successfully. To do so, the Suspense CD node generates an Update file.

To manage suspending and recycling records and batches, configure nodes to add and update a flag that tracks the status of suspended and recycled records and batches. The status values are:

Initialized (0). This flag is set when the node processes the record or batch. If no errors are found, the record or batch is passed to the next node in the node chain. If the status remains at 0, the record or batch is never suspended.
Failed (2). This flag is set when an error is found in the record or batch. The record or batch is sent to the NAR CC node, and then to the Suspense DC node, but not sent to the next node in the node chain. The Suspense DC node generates a Create file and sends it to BRM.
Successful (1). This flag is set when a record or batch is recycled, and no new error is found by the node that originally found the error. The record or batch is sent to two places:
- The next node in the node chain, such as the ECE DC node.
- The NAR CC node, and then to the Suspense DC node. The Suspense DC node generates an Update file and sends it to BRM to update the record or batch status in BRM Suspense Manager.

Figure 4-2 shows how the suspense flag is used in node chains.

Figure 4-2 Flags Used in Suspense and Recycle Node Chains

Description of "Figure 4-2 Flags Used in Suspense and Recycle Node Chains"

About Searchable Fields

When you configure Suspense Manager in BRM, you can specify which record and batch fields can be searched on and displayed in Suspense Management Center. These fields are called searchable fields. For more information, see "Using Custom Data With Suspense Manager" in BRM Suspending and Recycling Event Records.

To configure searchable fields in Offline Mediation Controller, you edit the Suspense DC node rule file. You specify the fields by using the BRM table names, for example:

QueryableTables "SUSP_USAGE_TELCO_INFO_T,SUSP_USAGE_TELCO_GSM_INFO_T";

For information about editing the Suspense DC node rule file, see Administration Client Online Help.

Configuring the File-Level Transaction Threshold

The file-level transaction threshold determines what percentage of records in a file can be suspended before the entire input file is rejected. This is an optional parameter.

To configure the file-level transaction threshold:

Stop the node manager that you want to reconfigure.
Open the OMC_home/bin/nodemgr.cfg file in a text editor.
Add the following entry to the file:
```
FILE_LEVEL_TRANSACTION_THRESHOLD 'value'
```
where value specifies the threshold percentage.

For example:
```
FILE_LEVEL_TRANSACTION_THRESHOLD '50'
```
Save and close the file.
Start the node manager.

About record Field Mapping

Note:

Oracle recommends record field mapping if you use Suspense Manager.

In Offline Mediation Controller, the NPL rules for a node allow values from the fields in the input stream to be assigned to the fields in the output stream, which are sent to the downstream nodes or external medium for processing.

The Suspense DC node serializes the CDR based on the output field names from the NPL mapping. Shorter designations may be used in place of the output field names by using record field mapping, which reduces the length of field names by replacing the field name with an ID. Whatever mapping is defined in the Suspense DC node, the reverse is required for the Recycle EP node.

The EDR Field Mapping Name field in the Mode tab of the Suspense DC node, refers to the database EDR_FIELD_MAPPING_T.NAME and the record field mapping is stored in the EDR_FLD_MAP_BUF_T table. Both tables are installed during a BRM installation or when you run the load_edr_field_mapping utility. Before using record field mapping, verify that these tables exist.

A record field mapping XML file is loaded into the database during installation of BRM Suspense Manager. You use the load_edr_field_mapping utility, a BRM component, to add or modify existing record field names and load new versions of the record field mapping XML file.

For more information, see "Integrating Event Record Field Mapping" in BRM Suspending and Recycling Event Records.

Working with SQL Files to Restore a Recycled CDR

The Recycle EP node restores the recycled CDRs based on SQL statements. Two types of SQL statements are used by the Recycle EP node:

Detail SQL, which is required.
Header SQL, which is optional.

The following sample SQL statement files are provided with the Recycle EP JAR file:

To retrieve serialized suspended CDRs in ASCII format, use the RecycleDetail.sql file.
To retrieve serialized suspended CDRs in records, use the RecycleEdr.sql file.
To retrieve serialized suspended CDRs in IMS format, which includes selected record common fields, use the RecycleIMS.sql file.
To retrieve header information, use the RecycleHeader.sql file, which is a generic SQL statement.

The data from Header SQL is set in every recycled CDR retrieved by the detailed SQL statement.

Installing the Sample Detail and Header SQL Files

To install the sample detail and header SQL files:

Go to the OMC_home/web/htdocs directory, where OMC_home is the directory in which Offline Mediation Controller is installed.

Extract the SQL files from the JAR file:

jar xvf Recycle.jar sql/RecycleDetail.sql sql/RecycleEdr.sql sql/RecyleIMS.sql sql/RecycleHeader.sql

The SQL files are placed in a sql directory.

Updating and Applying a Sample SQL File in the Recycle EP Node

To update and apply a sample SQL file in the Recycle EP node:

Choose one of the sample SQL statement files that best represents the format of the CDR before suspension, and update it according to your business requirements.
Note:

The following variables may be used in the SQL statement:
- ${RECYCLE_JOB_ID}, which is replaced by the job ID message sent by the AQ listener.
- ${PIPELINE_CATEGORY}, which is replaced by the name entered into the Category field in the SQL configuration tab of the Recycle EP node. A NULL value is given if the Category field is left blank.
In the SQL Header File and SQL Detail File fields in the SQL Files tab of the Recycle EP node, enter the full path and file name to the SQL header and SQL detail files.

SQL Statement Examples

The following example shows a detail SQL statement without editable fields:

SELECT   b.poid_id0, b.pipeline_name, r.recycle_mode, '', b.batch_id, 
         b.suspended_from_batch_id, b.recycle_key, e.edr_buf
FROM     suspended_usage_t b,
         susp_usage_edr_buf e, 
         susp_usage_recycle_t r 
WHERE    b.poid_id0 = e.obj_id0
  AND    b.recycle_obj_id0 = r.obj_id0 
  AND    b.recycle_obj_id0 = ${RECYCLE_JOB_ID} 
  AND    NVL(b.pipeline_category,'NULL') = ${PIPELINE_CATEGORY} 
ORDER BY b.poid_id0

The following example shows a detail SQL statement with editable fields:

SELECT  a.poid_id0, a.pipeline_name, a.recycle_mode, a.override_reasons,
        a.batch_id, a.suspended_from_batch_id, a.recycle_key, a.edr_buf,
        a.editable_flds
FROM
 ( SELECT b.poid_id0 , b.pipeline_name, r.recycle_mode,
          r.override_reasons,b.batch_id, b.suspended_from_batch_id, 
          b.recycle_key, e.edr_buf,
          'CalledId='|| t.calling_from|| CHR (9)||
          'calling_number='||t.called_to|| CHR (9)||
          'duration='|| t.call_duration|| CHR (9)||
          'start_time='|| t.start_time|| CHR (9)||
          'product_type='|| t.usage_type|| CHR (9)||
          'requestedInputVolume='|| t.bytes_in|| CHR (9)||
          'requestedOutputVolume='|| t.bytes_out|| CHR (9)||
          'cell_id='|| g.cell_id as editable_flds
FROM      suspended_usage_t b,
          susp_usage_telco_info_t t,
          susp_usage_telco_gsm_info_t g,
          susp_usage_edr_buf e,
          susp_usage_recycle_t r
WHERE     b.poid_id0 = t.obj_id0
     AND  b.poid_id0 = e.obj_id0
     AND  b.recycle_obj_id0 = r.obj_id0
     AND  b.poid_id0 = g.obj_id0
     AND  b.recycle_obj_id0 = ${RECYCLE_JOB_ID}
     AND  NVL(b.pipeline_category,'NULL') = ${PIPELINE_CATEGORY}) a
ORDER BY a.poid_id0

Configuring Suspense Errors

You can configure the following:

Which errors cause a record or batch to be recycled. You configure this in the nodes where errors occur.
The reasons and subreasons that are displayed in BRM Suspense Management Center for each of the errors. You configure this in BRM reason files. See "Changing the List of Suspense Reasons and Subreasons" in BRM Suspending and Recycling Event Records.

To configure a node to suspend a record or batch, you edit the node's rule file. You need to use Java hooks. This example shows the Java hook code for identifying an error:

if (in.product_type != "TEL" && in.product_type!="SMS") {
    // bad product type detected
    //   1) prepare output stream
    //   2) set suspended routing flag
    logInfo("inside wrong product type in.product_type=
       "+in.product_type);
    suspHandler.assemble(in, out, 5002, "ProductCheck",
    "ASCII");

In this example:

An error is recognized if the product is not a telco or SMS product.
The suspense flag is set to 2 (Suspended).
The error code is 5002.

The Offline Mediation Controller error codes are stored in the OMC_home/config/nodemgr/ocomc_errorcodes.xml file.

For more information, see "Suspense Error Configuration Examples".

Configuring New Error Codes

You incorporate error codes for errors that you want to detect into your node. Error codes are mapped to suspense reasons and subreasons in the Create and Update output files by the Suspense DC node. You can search for suspended event CDRs and batch CDR files using the error, reason, and subreason codes in Suspense Management Center.

To configure new Offline Mediation Controller error codes for suspended CDRs:

Stop the node manager.
Go to the OMC_home/config/nodemgr directory, where OMC_home is the directory in which Offline Mediation Controller is installed.
Open the ocomc_errorcodes.xml file in a text editor.

Add suspended error codes according to your specific business requirements by using the following XML format:

<OCOMCErrorCodes>
  <error id="1">
    <code>60001</code>
    <message>CANCEL_NOT_ALLOWED</message>
    <ReasonCode>13</ReasonCode>
    <SubReasonCode>0</SubReasonCode>
  </error>
</OCOMCErrorCodes>

Save and close the file.
Restart the node manager.

Note:

Any new Offline Mediation Controller error codes must be:

Added to the BRM_home/sys/data/config/pin_suspense_reason_code and BRM_home/sys/msgs/suspense_reason_code/suspense_reason_code.en_US files.
Loaded into the BRM database using the load_pin_suspense_reason_code and load_localized_strings utilities, which are components of BRM.

For more information, see "Changing the List of Suspense Reasons and Subreasons" in BRM Suspending and Recycling Event Records.

Working with the Offline Mediation Controller Error Code API

The OCOMCErrorCode Java API is used to access the errors defined in the ocomc_errorcodes.xml file. The following methods can be used:

OCOMCErrorCode.get(String errorMsg), this method will return the error code associated with the error message.
public static synchronized OCOMCError getError(String errorMessage), this method will return an instance of the OCOMCError object, which contains all the fields associated with the error.

Note:

You do not need to create an instance of the OCOMCErrorCode class. The node manager will add the class when it has been restarted.