This chapter describes how to install and customize Oracle Communications Billing and Revenue Management (BRM) Voucher Manager and Voucher Administration Center.
For information about Voucher Manager and Voucher Administration Center, see "About Managing Voucher Inventory".
Before installing Voucher Manager, you must install:
Third-Party software, which includes the PERL libraries and JRE required for installing BRM components. See "Installing the Third-Party Software" in BRM Installation Guide.
BRM.
Oracle 10g or Oracle 11g.
Before installing Voucher Administration Center, you must install:
BRM.
Voucher Manager is supported on the HP-UX IA64, Linux, Solaris, and AIX operating systems. For information on disk space requirements for these operating systems, see "Disk Space Requirements" in BRM Installation Guide.
Note:
Voucher Administration Center requires the Java Runtime Environment (JRE). It is included in the Voucher Administration Center package and is approximately 50 MB. If the JRE was already installed with another BRM client application, it will not be reinstalled.In addition to installing the Voucher Manager software, you must configure and load several text files before you can use Voucher Manager and Voucher Administration Center.
Before performing these configuration tasks, you should gather all the information about your voucher dealers, your recharge card types, and the batch and package numbers you will use.
Note:
You can perform these tasks in any order, but you must install Voucher Manager first.Define voucher device states. This involves two tasks:
Define and load the state transition model.
Load localized state descriptions.
See "Customizing Voucher Device States" and "Loading Voucher Device States".
Define order device states. See "Loading Voucher Order States".
Specify the services with which vouchers can be associated and load this information into the BRM database. See "Customizing and Loading Voucher Service Associations".
Associate the voucher devices with batch and part numbers and with batch and package quantities. See "Loading Voucher Details".
Define your voucher dealers and load this information into the database. You can also associate dealers with a specific voucher recharge card type. See "Loading Dealer Details".
Define your recharge card types. Each recharge card type is associated with an order configuration, which includes voucher dealer information, batch number, and order size. See "Loading Recharge Card Details".
Load the following locale files to localize the description fields in Voucher Administration Center:
To localize voucher device state descriptions, load the device_state_voucher.locale file located in BRM_Home/sys/msgs/voucher_devicestates. Even if you do not run a localized version of Voucher Administration Center, you need to load this file.
To localize voucher order state descriptions, load the order_state_voucher.locale file located in BRM_Home/sys/msgs/voucher_orderstates. Even if you do not run a localized version of Voucher Administration Center, you need to load this file.
Note:
If you have already installed the product, features that are already installed cannot be reinstalled without uninstalling them first. To reinstall a feature, uninstall it and then install it again.To install Voucher Manager:
Download the software to a temporary directory (temp_dir).
Important:
If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server.
You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid ”Out of Memory” error messages in the log file. For information, see "Increasing Heap Size to Avoid 'Out of Memory' Error Messages" in BRM Installation Guide.
Go to the directory where you installed the Third-Party package and source the source.me file.
Caution:
You must source the source.me file to proceed with installation, otherwise ”suitable JVM not found” and other error messages appear.Bash shell:
source source.me.sh
C shell:
source source.me.csh
Go to the temp_dir directory and enter this command:
7.5.0_VoucherMgr_platform_opt.bin
where, platform is the operating system name.
Note:
You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.(Optional) To install Voucher Manager server components separately on this computer or on another computer, select custom install when asked to specify the setup type. Select the components you are installing by typing their respective numbers and click Next. The components are:
Voucher Manager
Order Manager
Follow the instructions displayed during installation. The default installation directory for Voucher Manager is opt/portal/7.5.
Note:
The installation program does not prompt you for the installation directory if BRM or Voucher Manager is already installed on the machine and automatically installs the package at the BRM_Home location.Go to the directory where you installed the Voucher Manager package and source the source.me file:
Bash shell:
source source.me.sh
C shell:
source source.me.csh
Go to the BRM_Home/setup directory and run the pin_setup script.
Note:
The pin_setup script starts all required BRM processes.Your Voucher Manager installation is now complete.
To install Voucher Administration Center on Windows:
Download the software to a temporary directory (temp_dir).
Extract the downloaded .zip file to a temporary directory (temp_dir).
Go to temp_dir and run the setup.exe program. The installation wizard for Voucher Administration Center starts.
Answer the prompts in the installation wizard screens.
Your Voucher Administration Center installation is now complete.
Important:
This is a mandatory configuration task.You can customize voucher device states to support custom business logic.
You can create brand-specific device states. See "Device Management and Brands" in BRM Developer's Guide. However, you need to be careful to create device state mappings that work if you change the brand of a voucher. For example, if a device is in state 2 in one brand, it is still in that state when you change brands, but state 2 might be defined differently in a different brand.
To customize voucher device states, you edit the device_state_voucher.en_US sample file in the BRM_Home/sys/msgs/voucher_devicestates directory. You then use the load_localized_strings utility to load the contents of the file into the /strings objects. See "load_localized_strings" in BRM Developer's Guide.
When you run the load_localized_strings utility, use this command:
load_localized_strings device_state_voucher.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.For information on loading the device_state_voucher.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.
For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
If a voucher has no status displayed in Voucher Administration Center, it means that the device states for the voucher's brand have not been loaded. The brand administrator for the brand must do the following:
Load the pin_device_state_voucher file in BRM_Home/sys/data/config for that brand.
Load the device_state_voucher.locale file in BRM_Home/sys/msgs/voucher_devicestates if it changed or was not previously loaded.
Restart the Connection Manager (CM).
Restart Voucher Administration Center.
When you customize device states, you need to add the new device state name to the list of device states that is displayed in Voucher Administration Center. To do so, you run the load_localized_strings utility to load the contents of the device_state_voucher.locale file into /strings objects in the BRM database.
Note:
locale indicates the country. For example, the file used for US English is device_state_voucher.en_US.The device_state_voucher.locale file uses the same format as other files that are loaded by using the load_localized_strings utility. See the description of the required format of a string file in "About the String Manipulation Functions" in BRM Developer's Reference.
Note:
The load_localized_strings utility needs a configuration file in the directory from which you run the utility. See "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.Edit the device_state_voucher.locale file in BRM_Home/sys/msgs/voucher_devicestates.
Caution:
The load_localized_strings utility overwrites all existing notification data in the BRM database. If you are updating device state names, you cannot load new device state names only. You must load all notification data each time you run the load_localized_strings utility.Use the following command to run the load_localized_strings utility:
load_localized_strings device_state_voucher.en_US
Note:
Enter the appropriate file suffix for other locales. For example, to load device states in the German language, use the file named device_state_voucher.de.Look in the load_localized_strings.log file to find any errors. The log file is either in the directory from which the utility was started or in a directory specified in the configuration file.
For more information, see "load_localized_strings" in BRM Developer's Guide.
If Voucher Administration Center is running, stop and restart it.
To verify that the device state names were loaded, you can display the /strings objects by using the Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
Important:
This is a mandatory configuration task.The status of voucher orders is displayed in Voucher Administration Center. You cannot change the functionality of the order status; for example, you cannot add a custom status. However, you can localize the status definitions that are displayed.
Important:
Even if you do not use localized order status definitions, you need to load the order_state_voucher.locale file.To localize the file, you edit a copy of the order_state_voucher.en_US sample file in the BRM_Home/sys/msgs/voucher_orderstates directory and save the edited version with the correct locale file extension. To load the file, you use the load_localized_strings utility to load the contents of the file into the /strings objects. See "load_localized_strings" in BRM Developer's Guide.
When you run the load_localized_strings utility, use this command:
load_localized_strings order_state_voucher.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.For information on loading the order_state_voucher.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.
For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
Important:
This is a mandatory configuration task.To load dealer details into the database, you run the load_pin_dealers utility to load the data into the /config/dealers object. See "About Dealers".
Important:
The utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.In the pin_dealers file in BRM_Home/sys/data/config, enter the dealer names and code.
Save and close the file.
Use the following command to load the pin_dealers file:
load_pin_dealers dealer_input_file
For more information, see "load_pin_dealers".
Important:
This is a mandatory configuration task.To load recharge card details into the database, you run the load_pin_recharge_card_type utility to load the data into the /config/recharge_card_type object. See "About Recharge Card Types".
Important:
The utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.In the pin_recharge_card_type file located in BRM_Home/sys/data/config, enter the recharge card details.
Save and close the file.
Use the following command to load the pin_recharge_card_type file:
load_pin_recharge_card_type card_type_input_file
For more information, see "load_pin_recharge_card_type".
Important:
This is a mandatory configuration task.Voucher devices have the following states:
1 = New
2 = Used
3 = Expired
For information on voucher device states, see "About Voucher Device States".
These states are already defined in the pin_device_state_voucher file. You run the load_pin_device_state utility to load the data into the /config/device_state/voucher object.
Important:
The load_pin_device_state utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Edit the pin_device_state_voucher file in BRM_Home/sys/data/config.
Save and close the file.
Use the following command to load the pin_device_state file:
load_pin_device_state state_file_device
For more information, see "load_pin_device_state" in BRM Developer's Guide.
Important:
This is a mandatory configuration task.Voucher states are defined in the pin_order_state_voucher file. You run the load_pin_order_state utility to load the data into the /config/order_state/voucher object.
For information on voucher order states, see "About Managing Orders".
Important:
The load_pin_order_state utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Edit the pin_order_state_voucher file in BRM_Home/sys/data/config.
Save and close the file.
Use the following command to load the pin_order_state file:
load_pin_order_state state_file_order
For more information, see "load_pin_order_state" in BRM Developer's Guide.
Important:
This is a mandatory configuration task.The voucher service association file (BRM_Home/sys/data/config/pin_device_permit_map_voucher) specifies the services (/service objects) with which voucher devices (/device/voucher objects) can be associated in your BRM system. By default, vouchers can be associated with these services:
/service/telco/gsm/data
/service/telco/gsm/fax
/service/telco/gsm/sms
/service/telco/gsm/telephony
Note:
To enable vouchers to be associated with accounts, the pin_device_permit_map_voucher file also includes the /account object in the list of services with which /device/voucher objects can be associated.To use the voucher management features, you must load the voucher service association file into your BRM database. Before loading the file, you can customize the voucher service associations that it contains. See "Defining Device-to-Service Associations" in BRM Developer's Guide.
Note:
Voucher service associations are brand-aware and are associated with the root brand by default. See "Device Management and Brands" in BRM Developer's Guide.Important:
This is a mandatory configuration task.Voucher details are defined in the pin_voucher_config file. You run the load_pin_voucher_config utility to load the data into the /config/voucher object. See "About Voucher Details".
Important:
The load_pin_voucher_config utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Edit the pin_voucher_config file in BRM_Home/sys/data/config.
Save and close the pin_voucher_config file.
Use the following command to load the pin_voucher_config file:
load_pin_voucher_config voucher_input_file
For more information, see "load_pin_voucher_config".
You need voucher devices in your database so you can create accounts and then create a set of vouchers.
Note:
This procedure creates an order with five vouchers.To create a set of vouchers for testing:
In Voucher Administration Center, click the New Order icon or choose File - New Order.
Create an order using the following entries:
Customer Info tab:
Customer name: Telecom Services
Contact name: John Brown
Email address: jbrown@telecom.com
Address: 100 Main St
City: Fremont
State/Province: CA
Zip/Postal: 99999
Country: USA
Vendor Info tab:
Vendor name: Cell Corp
Contact name: Mary John
Email address: jmary@cellcorp.com
Address: 200 Main St
City: RedWood City
State/Province: CA
Zip/Postal: 12234
Country: USA
Order Details tab:
Recharge card: V02 Voucher
Order number: 1.35667
Note:
You can select either Recharge Card or Order number, but not both.Batch part number: BTH001
Package part number: PT02
Start serial number: 734536
This is the voucher card starting number for this order, which you enter in the last box of the Start serial number box.
Dealer: D001Airtel
Total Vouchers: 2500
If you select Total Vouchers and enter the quantity, the batch quantity is displayed in the Number of batches field.
Number of batches: 1
If you select Number of batches and enter the batch quantity, the package quantity is displayed in the Total Vouchers box.
Days: 10
Date: 2/19/04
Note:
You can select either Days or Date, but not both.Deal Selected: Voucher_$300
Click Generate File to generate the request file.
Select or create a directory in which to generate the request files. The file name is XXXXX.inp. This file will be request file sent to the voucher card vendor.
Save the file as XXXXX.out. This file will be the vendor response file.
Process the vendor response file.
Load the response file. For complete instructions on using Voucher Administration Center, see Voucher Administration Center Help.