3 Configuring Cartridges to Detect and Suspend Failed CDRs

This chapter describes how to configure Oracle Communications Offline Mediation Controller cartridges to detect and suspend failed call detail records (CDRs).

Before reading this chapter, you should be familiar with:

  • Oracle Communications Billing and Revenue Management (BRM) suspense handling and the BRM suspense components outlined in "Integrating Offline Mediation Controller with BRM".

  • Offline Mediation Controller cartridge concepts and Node Programming Language (NPL).

  • The Offline Mediation Controller ECE Cartridge Pack. For more information, see Offline Mediation Controller Elastic Charging Engine Cartridge Pack User Guide.

Deciding Your Suspense Handling Output Flow

As nodes in the node chain process individual CDRs and batch CDR files, any CDRs or batch CDR files that contain errors should be made available for suspense handling. For more information on Offline Mediation Controller suspense handling, see "About Suspending and Recycling Call Detail Records".

Decision Points

The Offline Mediation Controller suspense decision points need to be considered in order to implement a cartridge that detects errors.

Figure 3-1 shows the event CDR flow with suspense handling decision points.

Figure 3-1 Event Suspense Handling Error Decision Points

Description of Figure 3-1 follows
Description of "Figure 3-1 Event Suspense Handling Error Decision Points"

Event Flow Decision Points

The decision points for event suspense handling are as follows:

  1. The CDR enters the cartridge for processing, where:

    • If no errors are detected, the CDR passes through to the next cartridge in the processing flow of the node chain or is outputted to the target system.

    • If no errors are detected and the CDR contains the suspense ID field (previously passed through the suspense flow):

      1. The CDR passes through to the next cartridge in the processing flow of the node chain or is outputted to the target system.

      2. The CDR's input stream, error code, cartridge name, cartridge category, and the suspense ID are made available for the Suspense Distribution Cartridge (DC) node.

    • If an error is detected, the CDR's input stream, error code, cartridge name, and cartridge category are made available for the Suspense DC node.

    • If an error is detected and the CDR contains a suspense ID field (previously passed through the suspense flow), the CDR's input stream, error code, cartridge name, cartridge category, and the suspense ID are made available for the Suspense DC node.

    For a list of field names used in suspense handling, see "Suspense Fields".

  2. The Suspense DC node receives the suspended or recycled CDR, where:

    • If the suspended CDR does not contain a suspense ID field (a suspended CDR), the Suspense DC node:

      1. Changes the status to a suspended state, which displays as Suspended in Suspense Management Center, a component of BRM.

      2. Generates a Create file, which is in a format understood by Suspended Event (SE) Loader, which is a component of BRM.

    • If the suspended CDR contains a suspense ID field (a recycled CDR), the Suspense DC node:

      1. Changes the status to a suspended state, which displays as Suspended in Suspense Management Center.

      2. Generates an Update file, which is in a format understood by SE Loader.

    • If the suspended CDR contains a suspense ID field (a recycled CDR) and no longer contains an error, the Suspense DC node:

      1. Changes the status to a succeeded state, which displays as Succeeded in Suspense Management Center.

      2. Generates an Update file, which is in a format understood by SE Loader.

Batch Flow Decision Points

The decision points for batch suspense handling are as follows:

  1. The batch CDR file enters the batch-file-based collection cartridge (CC) for processing, where:

    • If no errors are detected, the CDRs in the batch CDR file pass through to the next cartridge in the processing flow of the node chain.

    • If no errors are detected and the batch CDR file was resubmitted (previously passed through the suspense flow):

      1. The CDRs in the batch CDR file pass through to the next cartridge in the processing flow of the node chain.

      2. Information on the resubmitted batch CDR file is made available for the Suspense DC node.

    • If an error is detected, the batch CDR file is put into an error directory and information on the batch CDR file is made available for the Suspense DC.

    • If an error is detected and the batch CDR file was resubmitted (previously passed through the suspense flow), information on the resubmitted batch CDR file is made available for the Suspense DC.

  2. The Suspense DC node receives information on the suspended or resubmitted batch CDR file and queries the SUSPENDED_BATCH_T table with the batch key for existing information on the batch CDR file, where:

    • If no suspended batch CDR file information exists, the Suspense DC node:

      1. Changes the status to a suspended state, which displays as Suspended in Suspense Management Center.

      2. Generates a Create file, which is in a format understood by Suspended Batch (SB) Loader, which is a component of BRM.

    • If suspended batch CDR file information exists (resubmitted batch CDR), the Suspense DC node:

      1. Changes the status to a suspended state, which displays as Suspended in Suspense Management Center.

      2. Generates an Update file, which is in a format understood by SB Loader.

    • If suspended batch CDR file information exists and the batch CDR file no longer contains an error, the Suspense DC node:

      1. Changes the status to a succeeded state, which displays as Succeeded in Suspense Management Center.

      2. Generates an Update file, which is in a format understood by SB Loader.

      Note:

      Each suspended batch CDR file is identified by the composite value of the following fields:

      • DETAIL:ASS_SUSPENSE_EXT:SOURCE_FILENAME, which is the input file.

        This field refers to the SUSPENDED_BATCH_T.INPUT_FILE column.

      • DETAIL:ASS_SUSPENSE_EXT:PIPELINE_NAME, which is the cartridge name that detected the error.

        This field refers to the SUSPENDED_BATCH_T.PIPELINE_NAME column.

      For a list of field names used in suspense handling, see "Suspense Fields".

Determining Your CDR Errors and Error Codes

Before implementing a cartridge that will detect CDRs or batch CDR files with errors, you need to decide what those errors are and which error codes to use from the BRM error code list.

The BRM error codes and corresponding reason codes can be found in the BRM_Home/sys/data/config/pin_suspense_reason_code file and the BRM_Home/sys/data/config/pin_batch_suspense_reason file, where BRM_Home is the directory in which BRM is installed.

The reason descriptions for the error codes are listed in the suspense_reason_code.en_US file and the batch_suspense_reason_code.en_US file, which can be found in the BRM_Home/sys/msgs/suspense_reason_code directory.

Note:

Localized versions of these files are available.

The Suspense DC maps error codes to suspense reasons, which can be divided into more specific suspense subreasons:

  • For event suspense handling, suspense reasons and subreasons are mapped to the error codes in the Create and Update output files.

  • For batch suspense handling, only suspense reasons are mapped to the error codes in the Create and Update output files.

You search for suspended event and batch CDRs using the error, reason, or subreason codes in Suspense Management Center.

To determine your CDR errors and error codes:

  1. Decide what errors your cartridge needs to detect.

  2. Check the BRM_Home/sys/data/config/pin_suspense_reason_code file and the BRM_Home/sys/data/config/pin_batch_suspense_reason file for the suspense handling error and reason codes that correspond to the errors you decided on in step 1.

  3. Incorporate the BRM error code in the cartridge that you have created to detect errors. For NPL examples, see "Error Detecting NPL Examples".

For specific business requirements, you can create new reasons and subreasons. New suspense reasons and subreasons must contain a valid suspense error code. For more information, see the discussion on changing reasons and subreasons in the BRM documentation.

Error Detecting NPL Examples

The following examples describe the NPL rule files for cartridges that detect event and batch CDR errors. Both examples use Java hook methods. For more information on Java hooks, see "Working with Suspense Java Hooks in NPL".

Product Type Error Event NPL Example

This example describes an NPL file for a node that detects and suspends event CDRs if the product type is incorrect.

Figure 3-2 shows the processing flow of a CDR in a node chain that contains three nodes:

  1. Node A, whose output stream is received by the Product Check EP node.

  2. Product Check EP node, which checks to see if the product type is TEL or SMS.

  3. Node B, which if no errors are detected, receives the input stream from the Product Check EP node.

Figure 3-2 Product Type Error Detection Flow

Description of Figure 3-2 follows
Description of "Figure 3-2 Product Type Error Detection Flow"

In the Product Check EP node, configure the NPL with a flag value that outputs the CDR to one of the following:

  • If the product type is not valid, the CDR is made available for the Suspense DC node, which changes the status to a suspended state and generates a Create file for the SE Loader.

  • If the product type is valid, the CDR outputs to Node B.

  • If the product type is valid and the CDR is recycled, the CDR is made available for the Suspense DC node, which changes the status to a succeeded state and generates an Update file for SE Loader.

Table 3-1 describes the NPL configuration for the Product Check EP node:

Table 3-1 Product Check EP NPL

NPL Description 
JavaHook suspHandler=oracle.communications.brm.nm.nplhook.SuspenseMethodHandlerImpl;

Java hook declaration.

 
InputRec { 
  String product_type;
  String calling_number;
} in;

Input stream from Node A.

 
OutputRec {
  String cdr_service;
  String eventType;
  String A_NUMBER;

Output stream to Node B.

 
  // internal flag
  Integer pSUSPENDED;
} out;

The routing Flag.

 
Expose for Routing {
  out.pSUSPENDED "susp";
}

Expose the routing flag and set the display name.

 
// initialize routing flag to 0
   out.pSUSPENDED=0;

Initialize the routing flag to 0, which if no errors are found sends the CDR to Node B.

 
if (in.product_type != "TEL" && in.product_type!="SMS") {
    // bad prodcut 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");

If the product type is incorrect, call the assemble Java hook method to clone the input stream to the output stream and add suspense fields for the given error code of 5002, cartridge name ProductCheck, and cartridge category ASCII.

 
    out.pSUSPENDED=2;

Set the routing flag to 2, which directs the suspended CDR to the Suspense DC for suspense handling.

 
} else {
    // good product type
    logInfo("good product type in.product_type=
       "+in.product_type);
  
    // prepare output stream by assigning input values
    if(in.product_type=="TEL"){
       out.cdr_service="VOICE";
       out.eventType="USAGE";
    }else if(in.product_type=="SMS"){
       out.cdr_service="SMS";
       out.eventType="SMS_USAGE";
    }
    out.A_NUMBER=in.calling_number;

If the product type is correct, prepare the output stream based on the input stream.

 
    // if this NAR was previously suspended (from
       recycle)
    //   1) add suspense fields to output stream
    //   2) set suspended routing flag
    if (suspHandler.isRecycled(in)>0) {
       logInfo("key suspense fields found, copying..." );
       suspHandler.append(in, out);

If the product type is correct and any suspense fields exist, such as, SUSPENSE_ID, append the suspense fields to the output stream.

 
       out.pSUSPENDED=1;
   }

Set the routing flag to 1, which directs the CDR to:

  1. Node B to continue processing.

  2. Suspense DC, which updates the status to Successful.

 
 }
write(out);

Writes out the stream.

Batch CDR File Error NPL Example

This example describes an NPL file for a node that detects and suspends a batch CDR file if it contains an error.

Figure 3-3 shows the processing flow of a batch CDR file in a node chain that contains two nodes:

  1. CDR CC node, which is responsible for processing input files received from the input directory.

  2. Node B, which if no errors are detected, receives the input stream from the CDR CC node.

Figure 3-3 Batch CDR File Error Detection Flow

Description of Figure 3-3 follows
Description of "Figure 3-3 Batch CDR File Error Detection Flow"

In the CDR CC node you configure the NPL with a flag value that outputs the CDR to one of the following:

  • If no suspended batch CDR file information exists, the CDR CC node moves the batch CDR file to an error directory and makes information on the suspended batch CDR file available for the Suspense DC node. The Suspense DC node changes the status to a suspended state and generates a Create file for SB Loader.

  • If the batch CDR file is valid, data processing continues to Node B.

  • If suspended batch CDR file information exists, the Suspense DC node changes the status to a succeeded state and generates an Update file for SB Loader.

Table 3-2 describes the NPL configuration for the CDR CC node:

Table 3-2 CDR CC NPL

NPL Description 
JavaHook suspHandler=oracle.communications.brm.nm.nplhook.SuspenseMethodHandlerImpl;

Java hook declaration.

 
InputRec { 
  String sourceFileName;
  Byte rejected;
  Byte resubmitted;
} in;

Input stream from the input directory.

Note: Not all the fields in the input stream are declared.

 
OutputRec {
  Integer pSUSPENDED;
} out;

Declares the routing Flag.

Note: Not all the fields in the output stream are declared.

 
Expose for Routing {
  out.pSUSPENDED "susp";
}

Expose the routing flag and set the display name.

 
/// local variables
String pipelineName;
String pipelineCategory;
String sourceDir;
String errorDir;
String sourcePrefix;
String sourceSuffix;
String targetPrefix;
String targetSuffix;
Integer count;
  
pipelineName="CDR Pipeline";
pipelineCategory="Wireless";
sourceDir="/input";
errorDir="batch/error";
sourcePrefix="test_";sourceSuffix="edr";
targetPrefix="err_";targetSuffix="bad";

Declare and initialize local variables.

 
// initialize routing flag to 0
out.pSUSPENDED=0;

Initialize the routing flag to 0.

 
if (in.rejected > 0) {
  // file was rejected
  logInfo("in rejected");
  // 1) move files from input directory to error
        directory
  count=SuspHandler.move(sourceDir, sourcePrefix,
              sourceSuffix, errorDir, targetPrefix,
              targetSuffix);
  // 2) create batch nar
  SuspHandler.assemble(out,
             sourcePrefix+in.sourceFileName+sourceSuffix,
             pipelineName,
             127,
             errorDir,
             targetPrefix+in.sourceFileName+targetSuffix,
             "Acme Wireless",
             "control10001",
             "01",
             "tap processing info",
             pipelineCategory);

If the batch CDR file is invalid, move the batch CDR file to an error directory and call the assemble Java hook method to add the suspended batch file information to the output stream.

 
  // 3) set suspended flag
  out.pSUSPENDED=2;

Sets the suspended Flag to 2.

 
} else {
  // file is good, output input stream, and set flag
  logInfo("in good");
  out=clone(in);

If the input file is valid, prepare the output stream based on the input stream.

 
  // if this file was previously suspended
     (from resubmit/recycle),
  // 1) add suspense fields to output stream
  // 2) set suspended routing flag
  if (in.resubmitted > 0) {

If the input file is valid and was previously suspended, append the suspense fields to the output stream.

 
  // send 0 error code to flag success
  SuspHandler.assemble(out,
            sourcePrefix+in.sourceFileName+sourceSuffix,
            pipelineName,
            0);
            out.pSUSPENDED=1;
  }

Set the suspended flag to 1.

 
 }
write(out);

Writes out the stream.