Skip Headers
Oracle® Communications Billing and Revenue Management Setting Up Pricing and Rating
Release 7.5

E16711-11
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

26 Using Event Extraction Manager

This chapter describes how to use Oracle Communications Billing and Revenue Management (BRM) Event Extraction Manager to extract prerated events for rerating.

Important:

Event Extraction Manager is packaged with Rated Event (RE) Loader.

Before extracting events, you must know the following information:

About the Event Extraction Manager

The Event Extraction Manager is the first application used in the rerating process. You use it to find and extract events from the BRM database that must be rerated by Pipeline Manager and then reloaded into the BRM database by the Rated Event (RE) Loader. For an overview, see "About Rerating Pipeline-Rated Events".

The Event Extraction Manager does not modify or process events, nor does it lock accounts in your database. This enables BRM and other applications to safely access accounts in the database while you are extracting events.

The Event Extraction Manager consists of the following components:

  • The event extract configuration file (pin.conf) specifies how the pin_event_extract utility connects to your BRM system and the size and name of the event extract output file.

  • The pin_event_extract.cfg file specifies the event search criteria.

  • The pin_event_extract utility searches the BRM database for events meeting the search criteria and writes the results to an output file.

  • The event extract output file contains the list of events to rerate.

Figure 26-1 shows the Event Extraction Manager:

Figure 26-1 Event Extraction Manager

Description of Figure 26-1 follows
Description of "Figure 26-1 Event Extraction Manager"

About the Event Extract Configuration File

The event extract configuration file (BRM_Home/apps/pin_event_extract/pin.conf) specifies how the pin_event_extract utility connects to your BRM system, the database from which to extract events, and the name and size of your event extract output file.

If you are extracting events from a multischema system, you must modify this file for each database schema in your system. For information, see "Extracting Events from a Multischema System".

For information on how to create this file, see "Configuring Connection and Output File Parameters".

About the pin_event_extract.cfg File

You use the event search file (BRM_Home/apps/pin_event_extract/pin_event_extract.cfg) to specify the criteria that the pin_event_extract utility uses to search for events in your BRM database. You can search for events based on a wide variety of criteria, including account number, product name, and impact category.

For information about the event search criteria, see "Event Search Criteria".

For information on creating a pin_event_extract.cfg file, see "Specifying Which Events to Extract for Rerating".

About the pin_event_extract Utility

The pin_event_extract utility builds a search query with the criteria specified in the pin_event_extract.cfg file and then executes it against the specified database schema. The search query selects only events that have a balance impact type of pipeline-prerated, indicating that Pipeline Manager has already rated the events.

About the Event Extract Output File

The pin_event_extract utility prints to a file the list of events meeting the search criteria. Results are written in tab-delimited columns conforming to the BRM CDR format. You send this file directly to Pipeline Manager for rerating.

The default implementation defines the event field to output file mapping for GSM and GPRS events. However, you can create additional categories by modifying the PCM_OP_BILL_POL_CONFIG_EET opcode.

When the number of events meeting the search criteria exceeds the specified maximum file size or number of EDRs, the utility generates multiple output files and appends a number, such as _1, _2, and so on, to each file name.

When you use the sequence number search criteria, the utility automatically appends a sequence number to the file name and ignores the specified maximum file size and number of EDRs.

Event Search Criteria

The Event Extraction Manager can search for events by using the criteria in Table 26-1.

To specify which events to extract:

  • To extract events generated for a specific brand, run the pin_event_extract utility with the -b parameter.

  • To extract events using all other criteria, edit the pin_event_extract.cfg file.

    Important:

    The event start time, event end time, and event type criteria are required.

    Table 26-1 Event Search Criteria

    Criteria Entry Name Description Required

    account number

    account
    

    Extracts events generated by the specified account.

    Caution: If you use this criteria, ensure the following:

    • All events for the specified accounts are available for rerating.

    • All specified accounts reside in the same database schema.

    • No other search criteria, other than the mandatory event start creation date, event end creation date, and event type, are set

    no

    brand name

    brand
    

    Extracts events generated for the specified brand. If you do not specify a brand, the utility uses the default root account.

    Note: To extract events by brand, you must run the pin_event_extract utility with the -b option.

    no

    deal name

    deal
    

    Extracts events generated by all products and discounts associated with the specified deal.

    Caution: Do not use this criteria with the product or rate plan search criteria. Doing so prevents the utility from extracting all events associated with the specified deal.

    no

    event occurrence start and end times

    event_start_time_stamp
    event_end_time_stamp
    

    Extracts events that occurred after the specified starting timestamp and before the specified ending timestamp. The start and end time are inclusive.

    yes

    event creation start and end times

    event_created_start_time_stamp
    event_created_end_time_stamp
    

    Extracts events created (loaded into the database) after the specified creation start timestamp and before the specified creation end timestamp. The start and end time are inclusive

    no

    event type

    event_category
    

    Extracts the specified event type. By default, this criteria is set to extract the /event/delayed/session/telco/gsm event type.

    yes

    G/L ID number

    gl_id
    

    Extracts events with the specified G/L ID.

    no

    impact category name

    impact_category
    

    Extracts events rated with the specified impact category.

    no

    item object number

    item_obj
    

    Extracts events generated for the specified item.

    no

    product name

    product
    

    Extracts events generated for the specified products.

    Caution: Do not use this criteria with the deal or rate plan search criteria.

    no

    rate plan name

    rate_plan
    

    Extracts events rated by the specified rate plan.

    Caution: Do not use this criteria with the deal or product search criteria.

    no

    resource ID

    resouce_id
    

    Extracts events with the specified resource ID. This criteria works best when the resource ID represents a non-currency asset such as Internet hours.

    no

    search event field

    search_event_type
    search_field
    search_parameter
    

    Extracts events of type search_event_type where search_field contains the specified search_parameter. For example, you can use this search criteria to extract events based on custom fields.

    Where:

    • search_event_type specifies the type of event to search. Only events of this type or a subclass of this event type are extracted.

    Important: All events of type search_event_type must contain the search_field specified. You must ensure that the storable class specified by the event type contains the search_field.

    • search_field specifies the field in the event used for event extraction. Only those events where search_field is equal to search_parameter are extracted.

    • search_parameter specifies the value of the search_field.

    Note: The search_parameter specified is used in addition to other search criteria specified in the pin_event_extract.cfg file.

    no

    sequence number

    file_sequence_number
    

    Extracts events processed with the specified file sequence number. This number is assigned by Pipeline Manager and then added to the event object when RE Loader loads the event into the database. This enables you to extract and rerate events that were processed at a particular time.

    You can find an event's file sequence number in the /batch/rel object.

    When you use this criteria, the pin_event_extract utility automatically appends the file sequence number to the output file name.

    Note: You can specify any sequence number other than 0. RE Loader uses 0 to indicate that Pipeline Manager did not assign a sequence number to the event.

    no

    service name

    service
    

    Extracts events generated for the specified service.

    Important: The specified service must correspond to a unique service type.

    no


Synchronizing Extraction and Rating Applications

It is important to rate all events before running the Event Extraction Manager. If there are events not yet rated when you run the Event Extraction Manager, your account balances will not be correct.

Event Extraction Manager and RE Loader use the same status table, REL_EVENT_EXTRACT_SYNC_T, to check if one of the other applications is running. If you attempt to start Event Extraction Manager while RE Loader is running, Event Extraction Manager fails to start and returns an error message.

However, if Event Extraction Manager or RE Loader terminate abnormally, the status table may be incorrectly left in a locked state. You must use the pin_event_extract utility's override option before you can extract events.

For more information, see "About Synchronizing Rating and Loading Applications".

Extracting Events

Extracting events includes the following general tasks:

  1. Configuring Connection and Output File Parameters.

  2. Specifying Which Events to Extract for Rerating.

  3. Running the pin_event_extract Utility.

  4. Troubleshooting Event Extraction Errors.

  5. Sending the Output File to Pipeline Manager.

Configuring Connection and Output File Parameters

To configure your connection and output file parameters:

  1. Open the event extract configuration file (BRM_Home/apps/pin_event_extract/pin.conf) in a text editor.

  2. Edit the connection and log file entries.

  3. Specify the EDR output file name.

    Note:

    • When you use the sequence number search criteria, the utility automatically appends the file sequence number to the file name.

    • When the output exceeds the specified file maximums, the utility automatically generates multiple output files and appends a number to each file name.

    - pin_event_extract filename SOL42_SenderReceiver
    

    Replace Sender with the code for the sender of the file and Receiver with the code for the recipient of the file. For example, if the sender's code is D00D1 and the receiver's code is SOL42, replace SenderReceiver with D00D1SOL42.

  4. Specify the UTC Time Offset. This is the difference between the local time and UTC time:

    - pin_event_extract UTCoffset Value
    
  5. Specify the specification version number:

    - pin_event_extract specvernum VersionNumber
    
  6. Specify the specification release version number:

    - pin_event_extract specrelver ReleaseNumber
    
  7. Specify the maximum number of EDR creation threads:

    - pin_event_extract num_threads MaximumNumber
    
  8. Specify the number of EDR records the Event Extraction Manager retrieves during each step search:

    - pin_event_extract step_size SearchNumber
    
  9. Specify the maximum size, in bytes, of the event extract output file. When the file size exceeds the specified maximum, the pin_event_extract utility creates additional output files and appends a number, such as _1, _2, and so on, to the file name.

    - pin_event_extract   maxfilesize   FileSize
    
  10. Specify the maximum number of EDRs allowed in each output file. When the number of EDRs exceeds the specified maximum, the pin_event_extract utility creates additional output files and appends a number, such as _1, _2, and so on, to the file name.

    - pin_event_extract   maxEDRs   MaximumEDRs
    
  11. Save and close the file.

Specifying Which Events to Extract for Rerating

The pin_event_extract utility finds the events for rerating by creating a search query. You specify the parameters for the search in the BRM_Home/apps/pin_event_extract/pin_event_extract.cfg file.

To extract events:

  1. Open the BRM_Home/apps/pin_event_extract/pin_event_extract.cfg file in a text editor.

  2. Set the mandatory event_start_time_stamp and event_end_time_stamp entries. The pin_event_extract utility extracts events that occurred between the specified start date and time and the end date and time (inclusive).

    Note:

    The time portion is optional. If you do not specify a time, the parameters default to midnight (00:00:00).
    event_start_time_stamp MM/DD/YYYY [ hh:mm:ss ]
    event_end_time_stamp MM/DD/YYYY [ hh:mm:ss ]
    

    where hh:mm:ss is the appropriate 24-hour time. For example, enter 16:00:00 to specify 4:00 p.m.

  3. Set the mandatory event_category entry:

    event_category     category
    category             EventTypeName
    

    where:

    • category specifies the type of event to extract. The default implementation includes the gsm and gprs event categories only, but you can create additional categories by modifying the PCM_OP_SUBSCRIPTION_POL_CONFIG_EET opcode.

    • EventTypeName specifies the name of the event you want extracted. For example, /event/delayed/activity/gprs.

      Tip:

      You can list multiple event types on one line by using colons (:) or semicolons (;) to delimit events.
  4. Set your search criteria. The pin_event_extract.cfg file includes examples and instructions.

    For an overview, see "Event Search Criteria".

  5. Save and close the file.

Extracting Events from Specific Partitions

Events are loaded into database tables that are partitioned by a period such as days, weeks, or months. You can improve event extraction performance by limiting the number of partitions from which events are extracted. To do this, specify the start and end dates of when the events were loaded into the database (their creation time).

For example, if your database tables are partitioned by months, you can extract events from a single partition only by specifying the start and end day of a single month.

To extract events from specific partitions:

  1. Open the BRM_Home/apps/pin_event_extract/pin_event_extract.cfg file in a text editor.

  2. Set the event_created_start_time_stamp and event_created_end_time_stamp entries. The pin_event_extract utility extracts events that were loaded into the database on or after the start time and on or before the end time.

    event_created_start_time_stamp MM/DD/YYYY hh:mm:ss
    event_created_end_time_stamp MM/DD/YYYY hh:mm:ss
    

    where:

    • MM/DD/YYYY is the month, day, and year.

    • hh:mm:ss is the time in 24-hour mode. For example, enter 16:00:00 to specify 4:00 p.m.

      Note:

      Specifying the time portion is mandatory. Entering only a day will return an error.

Sample pin_event_extract.cfg File for a Specific Rate Plan

The following sample pin_event_extract.cfg file extracts events that meet the following criteria:

  • Created between 6:00 p.m. on June 1, 2002, and 6:00 p.m. on August 30, 2002.

  • Is the following prerated GSM event: /event/delayed/session/telco/gsm.

  • Rated with the Free Saturdays rate plan.

event_start_time_stamp 06/01/2002 18:00:00
event_end_time_stamp 08/30/2002 18:00:00
  
event_category   gsm
gsm              /event/delayed/session/telco/gsm
  
rate_plan Free Saturdays

Sample pin_event_extract.cfg File for a Specific Sequence Number

The following sample pin_event_extract.cfg file extracts events that meet the following criteria:

  • Created between 10:00 a.m. on January 1, 2002 and 9:59:59 a.m. on January 31, 2002.

  • Represents a prerated GPRS event

  • Processed with the 777888999 sequence number

event_start_time_stamp 01/01/2002 10:00:00
event_end_time_stamp 01/31/2002 09:59:59
event_type /event/delayed/session/gprs
file_sequence_number 777888999

Running the pin_event_extract Utility

The pin_event_extract utility generates a search query with your specified search criteria.

To extract events:

  1. Ensure that RE Loader is not running.

    For information, see "Synchronizing Extraction and Rating Applications".

  2. Ensure that all events that you want to extract have been processed.

  3. Run the pin_event_extract utility.

    pin_event_extract [-f ConfigFileName] [-b]
    

Troubleshooting Event Extraction Errors

Event extraction may fail for several reasons:

  • RE Loader is currently running, preventing the Event Extraction Manager from starting. Wait for RE Loader to finish loading events before restarting the Event Extraction Manager.

  • The status table was incorrectly locked, preventing the Event Extraction Manager from starting. This can occur when one of the applications terminates abnormally and cannot reset the status table before exiting. To reset the status table:

    Caution:

    Do not use this option unless you are certain that RE Loader is stopped.
pin_event_extract -o TRUE

You can check the event extract log file, created by default in the BRM_Home/var/pin_event_extract directory, for information on why extraction failed.

After you fix the problem, you can safely rerun the pin_event_extract utility with the same pin_event_extract.cfg file.

Sending the Output File to Pipeline Manager

To begin rerating events, send the event extract output file to Pipeline Manager for processing. For information, see "About Rerating Pipeline-Rated Events".

Extracting Events from a Multischema System

The procedure for extracting events from a multischema system is almost identical to the procedure for a single-schema system except you must run the utility against each schema separately. For example, if the events you want to extract reside in three schemas, you must run the utility three times.

To extract events from a multischema system, perform the following general tasks on the system where Event Extraction Manager is installed:

  1. Specify the connection and output file parameters for the first schema by editing the event extract configuration file (BRM_Home/apps/pin_event_extract/pin.conf).

  2. Specify which events to extract by using the pin_event_extract.cfg file.

  3. Run the pin_event_extract utility and fix any errors.

  4. Change the connection and output file parameters for the next schema.

  5. Run the pin_event_extract utility and fix any errors.

  6. Repeat steps 4 and 5 until you have extracted events from all schemas.

Customizing How to Extract Events for Rerating

You can use the PCM_OP_SUBSCRIPTION_POL_CONFIG_EET policy opcode to customize which event fields are extracted for rerating; for example, you can modify which GPRS fields are extracted, or you can define the mapping for a custom event category.

PCM_OP_SUBSCRIPTION_POL_CONFIG_EET defines, for each event category, the event fields that Event Extraction Manager passes to the event extract output file. The default implementation defines the event-field-to-output-file mapping for GSM and GPRS event categories only.

This policy opcode is called by Event Extraction Manager worker threads when the tool returns a list of POIDs that meet the search criteria.

By default, the PCM_OP_SUBSCRIPTION_POL_CONFIG_EET policy opcode takes an event's POID and category name as input and performs the following functions:

  • Reads the entire event from the BRM database.

  • Maps predefined fields for GSM and GPRS events to a record buffer in the order received.

    Note:

    The pin_event_extract utility writes the contents of the record buffer to the event extract output file.

You can customize the PCM_OP_SUBSCRIPTION_POL_CONFIG_EET policy opcode to pass extended fields to the event extract output file. For example, you can modify which GPRS fields are passed to the output file, or you can define the mapping for a custom event category.

You can customize the following:

  • Read any additional event data based on the given POID.

  • Handle any new input formats. The policy opcode is written for the BRM CDR format.

  • Define the event field to output file mapping for any new categories.

  • Write data to the correct position in the record buffer.