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:
Basic BRM concepts
BRM system architecture
How to create and edit BRM configuration files
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 Rated Event (RE) Loader. For an overview, see "About Rerating Pipeline-Rated Events".
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.
Event Extraction Manager consists of the following components:
The event extract configuration file (pin.conf), which 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, which specifies the event search criteria
The pin_event_extract utility, which searches the BRM database for events meeting the search criteria and writes the results to an output file
The event extract output file, which contains the list of events to rerate
Figure 26-1 shows Event Extraction Manager:
The event extract configuration file (pin.conf), which specifies how the pin_event_extract utility connects to your BRM system, and the size and name 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".
The event search file (BRM_home/apps/pin_event_extract/pin_event_extract.cfg) specifies 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".
The pin_event_extract utility builds a search query with the criteria specified in the pin_event_extract.cfg file and then run 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.
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 Oracle 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 policy 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 Extraction Manager searches 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:
|
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 parameter. |
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 time stamp and before the specified ending time stamp. The start and end times are inclusive. |
yes |
event creation start and end times |
event_created_start_time_stamp event_created_end_time_stamp |
Extracts events loaded into the database after the specified creation start time stamp and before the specified creation end time stamp. The start and end times 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 general ledger 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 noncurrency 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 search_parameter. For example, you can use this search criteria to extract events based on custom fields.
Important: All events of type search_event_type must contain the search_field . You must ensure that the storable class specified by the event type contains search_field.
Note: search_parameter 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 |
It is important to rate all events before running Event Extraction Manager. If there are events not yet rated when you run 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 includes the following tasks:
To configure your connection and output file parameters:
Open the event extract configuration file (BRM_home/apps/pin_event_extract/pin.conf) in a text editor.
Edit the connection and log file entries.
Specify the EDR output file name:
- pin_event_extract filename SOL42_SenderReceiver
whereSender is the code for the sender of the file and Receiver is 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.
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.
Specify the UTC Time Offset: where UTC Time Offset is the difference between the local time and UTC time:
- pin_event_extract UTCoffset Value
Specify the specification version number:
- pin_event_extract specvernum VersionNumber
Specify the specification release version number:
- pin_event_extract specrelver ReleaseNumber
Specify the maximum number of EDR creation threads:
- pin_event_extract num_threads MaximumNumber
Specify the number of EDR records Event Extraction Manager retrieves during each step search:
- pin_event_extract step_size SearchNumber
Specify the maximum size, in bytes, of the event extract output file:
- pin_event_extract maxfilesize FileSize
When the file size exceeds the specified maximum, the pin_event_extract utility generates multiple output files and appends a number, such as _1, _2, and so on, to each file name.
Specify the maximum number of EDRs allowed in each output file.
- pin_event_extract maxEDRs MaximumEDRs
When the number of EDRs exceeds the specified maximum, the pin_event_extract utility generates multiple output files and appends a number, such as _1, _2, and so on, to each file name.
Save and close the file.
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:
Open the BRM_home/apps/pin_event_extract/pin_event_extract.cfg file in a text editor.
Set the event_start_time_stamp and event_end_time_stamp entries.
event_start_time_stampMM/DD/YYYY [ hh:mm:ss ] event_end_time_stamp MM/DD/YYYY[ hh:mm:ss ]
where hh:mm:ss time in 24-hour mode. For example, enter 16:00:00 to specify 4:00 p.m. If you do not specify hh:mm:ss, the time defaults to midnight (00:00:00).
The pin_event_extract utility extracts events that occurred between the specified start date and time and the end date and time (inclusive).
Set the 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 policy 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.Set your search criteria. The pin_event_extract.cfg file includes examples and instructions.
For an overview, see "Event Search Criteria".
Save and close the file.
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.
For example, if your database tables are partitioned by months, you can extract events from a single partition by specifying the start and end day of a single month.
To extract events from specific partitions:
Open the BRM_home/apps/pin_event_extract/pin_event_extract.cfg file in a text editor.
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:
Entering only a day returns an error.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
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
The pin_event_extract utility generates a search query with your specified search criteria.
To extract events:
Ensure that all events that you want to extract have been processed.
Ensure that RE Loader is not running.
For information, see "Synchronizing Extraction and Rating Applications".
Note:
If RE Loader and pin_event_extract are run simultaneously, pin_event_extract extracts only those records that are completely processed by RE Loader.Run the following command:
pin_event_extract [-f ConfigFileName] [-b]
Event extraction may fail for several reasons:
RE Loader is currently running, preventing Event Extraction Manager from starting. Wait for RE Loader to finish loading events before restarting Event Extraction Manager.
The status table was incorrectly locked, preventing 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.
To begin rerating events, send the event extract output file to Pipeline Manager for processing. For information, see "About Rerating Pipeline-Rated Events".
To extract events from a multischema system:
On the system on which Event Extraction Manager is installed, open the BRM_home/apps/pin_event_extract/pin.confin a text editor.
Specify which events to extract by using the pin_event_extract.cfg file.
Run the pin_event_extract utility and fix any errors.
Change the connection and output file parameters for the next schema.
Run the pin_event_extract utility and fix any errors.
Repeat steps 4 and 5 until you have extracted events from all schemas.
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.
The PCM_OP_SUBSCRIPTION_POL_CONFIG_EET policy opcode 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 do the following:
Read any additional event data based on the given POID
Handle any new input formats: the policy opcode is written for the Oracle CDR forma
Define the event-field-to-output-file mapping for any new categories
Write data to the correct position in the record buffer