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:

• Basic BRM concepts

• BRM system architecture

• How to create and edit BRM configuration files

About Event Extraction Manager

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:

Figure 26-1 Event Extraction Manager

Description of ''Figure 26-1 Event Extraction Manager''

About the Event Extract Configuration File

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".

About the pin_event_extract.cfg File

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".

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 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.

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 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 Search Criteria

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: All events for the specified accounts are available for rerating All specified accounts reside in the same database schema The event start time, event end time, and event type criteria are required.	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. 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 . You must ensure that the storable class specified by the event type contains 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 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

  
  

Synchronizing Extraction and Rating Applications

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

Extracting events includes the following 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:

   - 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.

4. Specify the UTC Time Offset: where UTC Time Offset 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 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:

   - 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.

10. 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.

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 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).

3. 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.

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.

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:

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:

     Entering only a day returns 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 all events that you want to extract have been processed.

2. 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.

3. Run the following command:

   pin_event_extract [-f ConfigFileName] [-b]
   

Troubleshooting Event Extraction Errors

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.

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

To extract events from a multischema system:

1. On the system on which Event Extraction Manager is installed, open the BRM_home/apps/pin_event_extract/pin.confin a text editor.

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.

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