I recently installed and configured the BRM pipeline rating using BRM’s optional Wireless Suite. I had a difficult time getting it to work because it requires installing many interdependent components and many manual configuration steps. Hopefully this blog will help you get it working without much difficulty. Most of the difficulty has to do with figuring out what steps are needed and why. The BRM documentation has most of the information you need but it is not in one place and it simply tells you to do this or that. It doesn’t do a good job at explaining what is needed to get the pre-configured wireless pipeline to work. It also doesn’t explain how to create accounts and CDRs that work with the these pre-configured items. I learned out a lot from getting it to work though. So here’s what I learned.
Pipeline rating is a completely standalone rating engine. These steps take you through the process of configuring the pipeline and BRM system so you can create accounts that the pipeline can work process and then create, rate and load CDRs into BRM. The pipeline needs to have rate plans, zones and other features loaded in the IFW database. BRM needs new event, service, device and item class-types configured. The pipeline uses some BRM database configuration items to work whereas BRM needs some FMs to handle functionality around the Customer Center extensions. You’ll also need to install the Telephone and SIM Card Administrator.
The basic steps to get it to work are listed here. More details are broken out in the section that follow.
- Install Customer Center Extensions.
- Install Server-side Components.
- Configuring the Wireless Registry File
- Configure the IFW Database with Default Rate Plans and Settings.
- Run pin_setup Scripts
- Configure PIN_REL
- Load the Telco GSM Event Map
- Merge and Load Telco Event Notification
- Create Portal Products, Deal, Plan and add to Plan List
- Load Device Service Map
- Load Item Type Mapping
- Setting up GSM Accounts and Services.
- Process CDR File
- Testing and Troubleshooting Pipeline Rating
Install Customer Center Extensions
The first things you’ll need to do is install a panel and it’s associated dialog boxes into Customer Center. This panel is needed to create accounts with telephony services. These services require phone numbers, SIM cards and IMEI numbers in order to maintain, rate, bill and provision the service. BRM added this panel so Customer Service Reps (CSRs) can select telephone numbers, SIM cards and IMEI numbers when creating new accounts.
You will also need to install admin tools used for creating blocks of telephone numbers and SIM cards. The install scripts for these admin tools and the Customer Center extensions are located on http://edelivery.oracle.com. Select “Oracle Communications Applications” in the drop-down and the OS you’re working with; e.g. Microsoft Windows 32-bit platform. Select search.
Select the “BRM Media Pack for Microsoft Windows (32-bit)” and download Oracle BRM clients for Windows. After it downloads unzip the file and install these three client components on your PC.
GSM_Mgr_CustCtrExt
NumberAdminCtr
SIMAdminCtr
The install scripts assume you have Customer Center already installed and it usually finds the installation directory by itself. The installation of these client side components is easy. After you unzip the packages, just execute the setup.exe file and follow the instructions.
Install Server-side Components
Since the pipeline rating engine is not part of BRM, some some new op-codes are needed by BRM. Although you have installed the pipeline rating engine on the server, you not done yet. There are several more components you will need. If you haven’t installed the pipeline rating engine, I blogged about it in, Common BRM Pipeline Installation Issues.
If you don’t have the install scripts shown below, you’ll need to go to Oracle e-delivery site and download the optional BRM components. It’s under the Oracle BRM Media Pack ->Oracle BRM Extensions.
Unzip the file and run these install scripts as the PIN user. The actual names may be a little different depending upon the version and platform you’re using.
7.4_WirelessSuite_linux_32_opt.bin
7.4_SIMMgr_linux_32_opt.bin
7.4_NumberMgr_linux_32_opt.bin
7.4_GPRS_Mgr_30_linux_32_opt.bin
7.4_GSM_Mgr_linux_32_opt.bin
Configuring the Wireless Registry File
When you install the Wireless Suite component, it comes with a pre-configured wireless pipeline. The registry for this pipeline is located in the the IFW_HOME/conf directory and is called wireless.reg. You will need to edit this file by entering the connection information you used for setting up the IFW and PIN database. It needs the database alias, and user name and passwords you used. There is one entry for the IFW database and two entries for the PIN database. You will need to encrypt the passwords using AES encryption.
Next you will need to create an IFW synchronization queue. The wireless pipeline registry, wireless.reg, calls the sync queue IFW_SYNC_QUEUE. It is created by running the pin_ifw_sync_oracle.pl scripts. I couldn’t get it to work taking some of the default values as shown in the script usage syntax.
pin_ifw_sync_oracle.pl create [-l username/password@databaseAlias] [-q queue_name -t queue_table]
After including the following command line options, I was able to get it to work. You will need to modify this for your particular environment.
perl pin_ifw_sync_oracle.pl create -l pin74/pin74@pindb -r 300 -s ‘tablespace PIN74 initrans 5 storage (initial 200k next 200k maxextents unlimited pctincrease 0 )’
Configure the IFW Database with Default Rate Plans and Settings.
The BRM Wireless Suite comes with a pre-configured set of rate plans, discounts, impact categories, etc. These settings are stored in the IFW_HOME/conf/pricingcenter/Oracle directory.
Edit the perl script called insertWIRELESS_SAMPLE.pl in this directory. Change the oracle connection properties to use the IFW database alias and user name and password you chose. When you run this script it will execute the insert statements contained in the SQL scripts located in this directory. You will notice that each SQL script is named after the IFW table it updates. This makes it very easy to see what is being added to the IFW database. As you can see, there are a lot of tables affected by running this perl script.
| ifw_alias_map.sql | ifw_apn_group.sql | ifw_apn_map.sql |
| ifw_calendar.sql | ifw_daycode.sql | ifw_destinationdesc.sql |
| ifw_discarding.sql | ifw_discountbalimpact.sql | ifw_discountcondition.sql |
| ifw_discountdetail.sql | ifw_discountmaster.sql | ifw_discountmdl_cnf.sql |
| ifw_discountmdl_ver.sql | ifw_discountmodel.sql | ifw_discountrule.sql |
| ifw_discountstep.sql | ifw_discounttrigger.sql | ifw_edrc_desc.sql |
| ifw_edrc_field.sql | ifw_exchange_rate.sql | ifw_glaccount.sql |
| ifw_holiday.sql | ifw_icproduct_all.sql | ifw_impact_category.sql |
| ifw_map_group.sql | ifw_mostcalled.sql | ifw_networkmodel.sql |
| ifw_networkoper.sql | ifw_pipeline.sql | ifw_pricemodel.sql |
| ifw_pricemodel_step.sql | ifw_rateplan_cnf.sql | ifw_rateplan.sql |
| ifw_rateplan_ver.sql | ifw_ref_map.sql | ifw_resource.sql |
| ifw_rsc_group.sql | ifw_seqcheck.sql | ifw_serviceclass.sql |
| ifw_servicecode_map.sql | ifw_service.sql | ifw_specialday_lnk.sql |
| ifw_specialdayrate.sql | ifw_splittingtype_all.sql | ifw_standard_zone.sql |
| ifw_taxcode.sql | ifw_taxgroup.sql | ifw_tax.sql |
| ifw_timeinterval.sql | ifw_timemodel_lnk.sql | ifw_timemodel.sql |
| ifw_timezone.sql | ifw_uom.sql | ifw_usageclass_map.sql |
| ifw_usageclass.sql | ifw_usagescenario_map.sql | ifw_usagetype.sql |
| ifw_usc_group.sql | ifw_zonemodel.sql |
To run this command, be sure to redirect the output to a file. It streams a bunch of information to the standard output. It doesn’t output to a log file so you may want to look back this file to be sure it ran properly.
Run pin_setup Scripts
As a pin user, go to $PIN_HOME/setup/scripts
Run the pin_cmp_tcframework.pl file. This install script creates a bunch of new classes (tables) in the PIN database. Expand the nodes below to see what tables where created:
Service Objects:
/service/telco/ /service/telco/gsm/roaming
Event Objects
/event/activity/telco /event/session/telco /event/delayed/activity/telco /event/delayed/session/telco /event/delayed/activity/telco/roaming /event/delayed/session/telco/gsm/roaming /event/svc_order /event/svc_order/attribute /event/provisioning /event/provisioning/service_order
Config Objects:
/config/telco/provisioning /config/telco/provisioning/fieldlist /config/telco/service_order_state /config/telco/service_order_state/telco /config/service_framework /config/service_framework/permitted_service_types/ /config/account_era
Run the perl pin_cmp_gsm.pl script Expand the following nodes to see what tables (classes) are created.
Service Objects
/service/settlement /service/settlement/roaming /service/telco/gsm /service/telco/gsm/data /service/telco/gsm/fax /service/telco/gsm/sms /service/telco/gsm/telephony /service/telco/gsm/roaming /service/settlement/roaming /service/settlement/roaming/incollect /service/settlement/roaming/outcollect
Event Objects:
/event/activity/settlement /event/session/telco/gsm /event/delayed/session/telco/gsm /event/delayed/session/telco/gsm/roaming /event/provisioning/service_order/telco/gsm /event/provisioning/service_order/telco/gsm/data /event/provisioning/service_order/telco/gsm/fax /event/provisioning/service_order/telco/gsm/sms /event/provisioning/service_order/telco/gsm/telephony
Config Objects:
/config/telco/gsm /config/telco/gsm/data /config/telco/gsm/fax /config/telco/gsm/sms /config/telco/gsm/telephony /config/telco/service_order_state/gsm /config/telco/service_order_state/data /config/telco/service_order_state/fax /config/telco/service_order_state/sms /config/telco/service_order_state/telephony
Active_session objects:
/active_session/telco/gsm /active_session/telco /active/session/telco/gsm
Run the pin_cnf_tcframework.pl script. This will add the following FMs to the CM pin.conf file. These FMs contain opcodes used by the Customer Center.
| fm_prov | fm_prov_pol |
| fm_tcf | fm_tcf_pol |
| fm_trans_pol |
Run the pin_cmf_dm_prov_telco.pl and pin_cnf_dm_prov_telco.pl
This will configure the CM pin.conf file and dm_prov_telco pin.conf file. You may also want to edit the start_all and stop_all script so that dm_prov_telco start and stops with the rest of the CM and DMs.
Configure PIN_REL
There are several traps you can fall into trying to get the pin_rel utility to work for the first time. You will need to run some setup/scripts, modify the user $PATH and make sure Oracle sqlldr is installed on the server. This section will help you avoid some common problems.
First, the pin_rel utility requires some new tables in the database schema to operate. Go to the setup/scripts directory and run the pin_cmf_rel.pl and pin_cnf_rel.pl. Next add the $PIN_HOME/apps/pin_rel to the pin user $PATH. And finally be sure Oracle sqlldr is installed on the server.
The pin_rel utility use SQL Loader (sqlldr) to load events into the BRM database. To see if it is installed on your server, executing sqlldr from the command line as the pin user. If it can’t be found check to be sure the $ORACLE_HOME/bin directory is in the path. If sqlldr isn’t in the bin directory, then install it. It’s part of the Oracle database installation so you will basically have to install Oracle on the server. Since you don’t actually need a configured database on the server, skipping this step during installation will save you some time.
For performance reasons you may want to run on the database server. When you run CDRs through the pipeline, you can map the output to a network drive or copy the files to database server. For our testing purposes running it on the BRM server is sufficient. If you have a large amounts of EDRs to process in production and to load into BRM, then you may need to move the pin_rel app over to the database server.
Load the Telco GSM Event Map
The Pricing Center needs to be configured to recognize the new event and service objects loaded in prior steps. Fortunately the new event map is created for you. This event map comes already merged with BRM base-line event maps. If you’re working with a baseline BRM installation, you just have to load them into the database.
Change directory to sys/data/config directory and run the command:
load_event_map -dv pin_event_map_telco_gsm
If you have custom events already loaded, then be sure to edit the pin_event_map_telco_gsm file before you run this command. This command will overright the changes made to the default event map, if you don’t. If you forget, just rerun the command with custom events added to this file.
Merge and Load Telco Event Notification
The Telco provisioning is integrated through the event notification framework. When new products and services are purchased for an account, the event notification framework needs to fire-off these op-codes. These op-codes will perform functionality required to provisioning the new telephony services through BRMs provisioning framework.
| PCM_OP_TELCO_SVC_LISTENER | 4008 |
| PCM_OP_TELCO_APPLY_PARAMETER | 4009 |
| PCM_OP_TELCO_PROPAGATE_STATUS | 4010 |
| PCM_OP_TELCO_PROV_CREATE_SVC_ORDER | 4016 |
| PCM_OP_TELCO_PROV_HANDLE_SVC_ORDER | 4017 |
| PCM_OP_TELCO_PROV_UPDATE_PROV_OBJECT | 4019 |
To enable the provisioning framework, change to following directory to sys/data/config and execute
load_pin_notify pin_notify_telco
Create Portal Products, Deal, Plan and add to Plan List
In this section you will create a product, deal and a plan that can be purchased against accounts and rate CDRs through the pipeline. We will use one of the rate plans inserted in the pipeline database with the insertWIRELESS_SAMPLE.pl script described above. Start Pricing Center and connect to the PIN database. Click on the create product icon, enter a name and select in the drop-down list Applies To: /service/telco/gsm/telephony.
Accept all the default values and when you get the prompt, “Do you want to add or change rates and folds for this product?”, click on “Yes”. Now add an Event Map and locate “Delayed Session GSM Session”. This should give you a menu of Pipeline Single Rate Plans. Click on “Search/Reload” This pop-up window should look like this:
Click and then “Select” the GSM Sample Rate Plan. Apply changes. Next create a deal and a plan for this product. Add the Plan to the default plan list. Commit changes to the database.
Load Device Service Map
load_pin_device_permit_map pin_device_permit_map_sim_telco_gsm
load_pin_device_permit_map pin_device_permit_map_num_telco_gsm
Load Item Type Mapping
The events rated by the pipeline engine requires an /item object to associate these charges together for an account. The documentation provides examples for associating charge from New York or California to /item/gsm/new_york or item/gsm/california. For sake of simplicity we will just associate all pipeline rates events to /item/usage/gsm. To do this, you will need to edit two xml files in the $PIN_HOME/sys/data/pricing/examples directory; config_item_tags.xml and config_item_types.xml. Add the contents for <ItemTagElement> to the following files as shown below:
config_item_tags.xml
<ItemTagElement>
<ItemTag>gsm</ItemTag>
<EventType>/event/delayed/session/telco/*</EventType>
<ServiceType>/service/telco/gsm/*</ServiceType>
</ItemTagElement>
config_items_types.xml
<ItemTypeElement>
<ItemTag>gsm</ItemTag>
<ItemDescription>GSM Usage</ItemDescription>
<ItemType precreate=”true” type=”cumulative”>/item/usage/gsm</ItemType>
</ItemTypeElement>
To load these configuration files using the following utilities:
load_config_item_tags -dv config_item_tags.xml
load_config_item_types -dv config_item_types.xml
Using Developer Center extend the /item/usage to /item/usage/gsm. To do this start Developer Center, click on the Storable Class Editor and click on the /item/usage class in the class window. Then click File->New->Class and add “/gsm” to the base class. And finally click on File->Commit Class to Database
If you get a permission error message committing these changes, recall that the DM_ORACLE pin.conf file needs to be set to enabled to changes to the class and field definitions, see below:
- dm dd_write_enable_fields 1
- dm dd_write_enable_objects 1
You will have to restart the BRM to load these changes.
Setting up GSM Accounts and Services.
Before you can create accounts using the GSM plan created in Pricing Center, you will need to load up a set of test phone numbers and SIM cards to use. What SIM card and phone number you specify will matter for testing. For instance, the pipeline will not rate any out of network calls. So all the CDRs you create to test in the pipeline will have to use phone numbers associated with accounts and services setup in BRM. But before you can do that you will need to establish a block of available numbers to select from.
I found the documentation very good for learning how to use the Number and SIM Card Administrator. These applications are used to set up a block of numbers and SIM cards that can be consumed by account telephony services in BRM. The Number Administrator was straight forward and easy to use. There are a couple things to note, however, when using the Number and SIM Card Administrator.
1) Load SIM Card types before running the SIM Card Administrator. From the PIN_HOME/sys/msgs/simcardtypes directory load the SIM card types by using the load_localized_string utility from the command line:
load_localized_strings sim_card_types.en_US
2) Use known good test SIM cards numbers. To create a block of SIM cards you first have to order them in the SIM Card Administrator. After they are ordered you will need to fulfill the order. To make this easier, refer to the end of documentation for configuring the SIM Card Administrator. It contains a set of test SIM card numbers you can use to test with. If you don’t use these numbers, you’ll have to figure out valid fulfillment data used to activate the order.
Normally you would export a file and send this file to a supplier of SIM cards. The SIM card manufacturer would return an order fulfillment so you can activate the numbers for BRM to consume. For testing purposes you will export the order and modify the order with test data provided in the documentation. As described in the documentation, it involves appending some order fulfillment code to the end of the exported order and then loading them back into the SIM Card Administrator.
3) Set the status to “Not Specified” when searching for SIM cards in the Customer Administrator. When you search for SIM cards in the Customer Center, it searches through available devices (/device/sim) for SIM cards with a status of released. You can either configure the SIM Card Administrator to include “New” status, or change the status to “Not Specified”.
4) Coordinate test phone numbers with zone mapping values and CDR test data. If you plan to leverage pre-configured zone mappings and sample CDRs then you might consider creating a block of phone numbers to include these numbers. If you don’t you’ll have to edit the sample CDRs to include the ones you did use and determine how the numbers are rated and mapped in the zone map. For reference, I included some phone numbers used in the sample CDRs. These CDRs I found in the IFW_HOME/data/in directory in a file called test_cdr.orig. The second and third field in the files are the source and destination numbers of the CDR. Again, both source and destination numbers need to be used by accounts in BRM for them to rate. No out of network phone calls will work.
TEL;00491732410;004941067600;20011114184300;300;0;0;NORM;123456; TEL;00491732411;004941067600;20011114184300;270;0;0;NORM;123456; TEL;00491732412;004941067600;20011114184300;110;0;0;NORM;123456; DAT;00491732413;004941067600;20011114184300;50;0;0;NORM;123456; FAX;00491732414;004941067600;20011114184300;12;0;0;NORM;123456; TEL;00491732415;004941067600;20011114184300;1;0;0;NORM;123456; SMS;00491732416;004941067600;20011114184300;63;0;0;NORM;123456; TEL;00491732417;004941067600;20011114184300;37;0;0;NORM;123456; TEL;00491732418;004941067600;20011114184300;132;0;0;NORM;123456; TEL;00491732419;004941067600;20011114184300;60;0;0;NORM;123456; TEL;00491732420;004941067600##;20040601184300;300;0;0;NORM;123456; GPRT;00491732410;0049;20011114184510;300;78965;5054;;001121;hamburg.portal.com GPR;00491732410;0049;20011114184510;300;78965;5054;;001121;hamburg.portal.com
And these where pulled out of the wireless.readme file:
TEL;00491729183333;004941067600;20011114184510;300;0;0;;; TEL;00491729183333;004941067600;20011114184510;300;0;0;Mail;47113; TEL;00491729183333;004941067600;20011114184510;300;0;0;Conf;98765; TEL;00491729183333;004941067600;20011114184510;300;0;0;MOC;238476;
Once you have a block of numbers and SIM cards configured, you can create accounts. Using Customer Center, create accounts to include phone numbers you plan to use for testing.
Process CDR File
Start up pipeline using the following command in $IFW_HOME.
ifw -r /conf/wireless.reg
Create CDR file and place into /conf/data/in
Testing and Troubleshooting Pipeline Rating
The error messages provided by the Pipeline Rating engine makes is somewhat easy locate problems. The most helpful messages are located in the $IFW_HOME/log/stream directory. You will find two sets of logs for each input file, Stream_test_XXXX.edr.log and log_test_XXXX.edr.log. If you have CDRs in the data/in directory that don’t make it to the data/out/gsm/* check here for errors. The most common errors I found where problems with the ITEM_TAG value (being null) and problems with out of network phone numbers. If you’re having trouble with ITEM_TAG numbers, review the section on Item Tag Mapping. If you have error message for out of network phone numbers, remember that both source and destination phone numbers need to be consumed by accounts (in network) in order for them to be rated.
