39 About Managing Voucher Inventory

This chapter describes how to manage voucher inventory in your Oracle Communications Billing and Revenue Management (BRM) system by using Voucher Manager and Voucher Administration Center.

Important:

Voucher Manager and Voucher Administration Center are optional components, not part of base BRM.

Before using Voucher Manager and Voucher Administration Center, you need to know the following information:

Basic BRM concepts. See BRM Concepts.
BRM system architecture. See "BRM System Architecture" in BRM Concepts.
How to create and edit BRM configuration files. See "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

About Managing Voucher Cards

You use Voucher Manager and Voucher Administration Center to manage the life cycle of voucher cards.

Voucher Manager includes the opcodes and storable classes required for creating and managing voucher card devices in the BRM database.
Voucher Administration Center is the client application that you use to create and process voucher orders and voucher brands.

You use Customer Center to assign voucher cards to customers and manage voucher cards in customer accounts. See "Getting Information about Voucher Usage".

About Creating Vouchers

Use Voucher Administration Center to order voucher cards from a vendor. For complete instructions on using Voucher Administration Center, see the Voucher Administration Center Help.

Important:

Before you create an order, you must configure voucher data. See "Mandatory Configuration Tasks". You must also create voucher deals in Pricing Center. See "About Voucher Deals".
When creating orders, do not log on to Voucher Administration Center as root. If you do, Voucher Administration Center will stop responding when you try to select any deal, other than Product Purchase Fee Event, to retrieve deal information for the order. Instead, log on as a CSR user.

To create vouchers:

Create an order in Voucher Administration Center.

The order is stored in the BRM database and can be updated or canceled. See "About Voucher Orders".
Create one or more vendor request files. See "Vendor Request Files and Voucher Orders".
Send the vendor request files to the vendor.

You can use any file transfer method, such as FTP or email.
Receive the vendor response files and process them in Voucher Administration Center. See "Vendor Response Files and Voucher Devices".

This creates an /order/voucher object for each voucher card.

Figure 39-1 shows the process for creating voucher cards:

Figure 39-1 Voucher Card Creation Process

Description of ''Figure 39-1 Voucher Card Creation Process''

About Voucher Orders

When you create an order, you can specify the following order attributes:

Customer name and address information. This is usually your company.
Vendor name and address of the vendor who creates the vouchers.

Note:
There are limitations on how many characters you can use for each piece of customer or vendor information. These limitations allow more characters than you will probably use. For more information, see the /order object definition.
Voucher card attributes:
- Quantity of voucher cards
- Package and batch part numbers and quantity
- Voucher card number
- Brand
- Deal associated with the voucher
- Voucher card expiration date
- Dealer name

Figure 39-2 shows the Order Details tab you use to specify voucher order attributes in Voucher Administration Center:

Figure 39-2 Order Details Tab

Description of ''Figure 39-2 Order Details Tab''

About Voucher Deals

Customers purchase vouchers by purchasing a voucher deal. You create a voucher deal in Pricing Center, following the normal procedure. The deal must have the following attributes:

There must be only one product in the deal.
There must be only one balance impact in the product.
The product must rate only a product purchase fee event.
The product must be an item product.

For information about creating deals, see "About Deals" in BRM Setting Up Pricing and Rating.

About Dealers

Dealers are the voucher card distributors from whom you buy the voucher cards. A dealer can also be the service provider. You must load the dealers details (dealer name and dealer code) before you start using Voucher Manager and Voucher Administration Center.

The dealer codes are used by BRM system and dealer names are displayed in Voucher Administration Center. You can also search for dealer names, and display them in reports.

Use the load_pin_dealers utility to load the dealer information into the BRM database. See "Loading Dealer Details".

About Recharge Card Types

You must create recharge card types and load them into the database. For example, a card type might be $20 Promotional Card. To create a card type, you must enter the recharge card details:

Dealer name.
Dealer code.
Recharge card type (a description).
Recharge card code.

The recharge codes are used by BRM system and recharge card types are displayed in Voucher Administration Center.

You must load the recharge card details before you start using Voucher Manager and Voucher Administration Center. Use the pin_recharge_card_type utility to load the recharge card information into the BRM database. See "Loading Recharge Card Details".

About Voucher Details

You must define voucher details such as batch part number, package part number, package quantity, and batch quantity before using Voucher Manager and Voucher Administration Center:

A package is a set of vouchers with the same recharge amount.
A batch is a carton containing several packages of vouchers.

The batch part number and package part number are used to create the voucher card number. The unique serial number for each voucher card is the concatenation of the batch number, the package part number, and the voucher card number. For example, if you enter 0002 for the batch number, 0003 for the package part number, and 1000 for the starting number, the unique serial number would be 000200031000.

Use the load_pin_voucher_config utility to load the voucher information into the BRM database. See "Loading Voucher Details".

About Managing Orders

When you create and manage voucher orders, BRM assigns a state to the order. You use Voucher Administration Center to display the status of an order.

Note:

Voucher orders are stored in the database as /order/voucher objects.

Voucher Manager sets an order's status as follows:

When you create an order, the status is New. You can save a new order or cancel it. When you cancel an order, the status is set to Cancelled. You can also update an order if it has a status of New.
After you create the vendor request file, the status is changed to Request. When an order has the Request status, you cannot cancel or modify it.
When you begin processing vendor response files, the status is changed to Partial Receive.
After you process all the vendor response files in an order, the status is changed to Received.

When the order has a Received or Partial Receive status, you cannot change the order attributes. You can search for orders of any status.

The voucher order states are represented as numbers in Voucher Administration Center.

1 = New
2 = Request
3 = Received
4 = Partial Receive
5 = Cancelled

Figure 39-3 shows the various order states:

Figure 39-3 Order States

Description of ''Figure 39-3 Order States''

About Modifying Orders

You use Voucher Administration Center to modify an order. You can search for orders by entering a date range, order ID, recharge card type, dealer name, or order state value. For instructions on modifying vouchers, see the Voucher Administration Center Help.

About Voucher Request and Response Files

You manage orders with your voucher vendor by exchanging request and response files.

The request files include information about the order, and are used by the vendor to create the vouchers. Request files specify the quantity of vouchers and the voucher attributes, such as the customer name and voucher format.
The response files contain information from the vendor about the vouchers. You load this data into the BRM database.

Note:
Before you create request files or upload response files, you must create vendor request and response file templates. See "About Request and Response File Templates".

Before creating the request file, you must set the configuration values. The configuration information includes directory path name, the standard naming for the request file, as well as the encryption algorithm.

By default the voucher PIN is encrypted when it is stored in the database. An encrypted request file consists of the serial number, PIN, recharge type, dealer name, quantity, order creation date, order reference number as well as sender and receiver contact information.

Note:

Multiple vendor request files are created automatically, based on the size of the order. However, you need to process each vendor response file individually.

Vendor Request Files and Voucher Orders

Voucher Administration Center generates vendor request files using the following naming convention:

CustomerNamennnnn.inp

where:

CustomerName is the name in the Customer name field when creating the order.
nnnnn specifies the order in which the vendor request files are generated. The number is incremented for each vendor request file generated by an order. For example, the first vendor request file in an order is 00001.

For example, if the customer name is Oracle, the first vendor request file in the order is named Oracle00001.inp.

Important:

All orders that you create for the same customer use the same file names. Therefore, you should always put request files in a new or empty folder for each order, so files from previous orders are not overwritten.

Vendor request files cannot specify more than 5,000 vouchers. If you create an order for more than 5,000 vouchers, the order is automatically divided into multiple files. For example, if you create an order for 50,000 vouchers, Voucher Administration Center creates 10 vendor request files of 5,000 vouchers each.

You can create a maximum order of 499,995,000 vouchers, which would create 99,999 vendor request files.

You use Voucher Manager to:

Update the status of the order from New to Request.
Set the voucher expiration date.
Set the request file name and creation date.

You can change the default values for the maximum quantity of vouchers in an order and the maximum number of vouchers in a request file.

Vendor Response Files and Voucher Devices

Vendor response files use the following naming convention:

CustomerName_nnnnn.out

where:

CustomerName is the name in the Customer name field when creating the order.
nnnnn is the file order number, which is incremented for each order. The first file in an order uses 00001.

For example, if the customer name is ”Oracle,” the first file in an order is named Oracle00001.out.

You use Voucher Administration Center to process the vendor response files and create devices.

After the vendor response file is processed, the state of the order is changed to Received. In case a partial response file is received, the order is state is changed to Partial Receive.

The voucher device created by this process consists of the voucher pin, voucher serial number, dealer name, expiration date, and status. The various states of voucher devices are new, used, and expired. See "About Voucher Device States".

You can modify voucher devices. See "About Managing Vouchers".

About Request and Response File Templates

To process vendor request and response files from various vendors, you create vendor file templates. These templates define the request and response file formats for each vendor. You typically use one template for each vendor. A basic format is available in the BRM database, and you can create a new template or open an existing template and modify it.

You create templates by using Voucher Administration Center, and you specify a template when generating the request and response files. The templates are stored in XML format in the BRM database as /config/inventory_mgmt_template objects.

Figure 39-4 shows a sample request template:

Figure 39-4 Sample Request Template

Description of ''Figure 39-4 Sample Request Template''

Figure 39-5 shows a sample response template:

Figure 39-5 Sample Response Template

Description of ''Figure 39-5 Sample Response Template''

About Request and Response File Encryption

You can encrypt the vendor request file, and you can decrypt the vendor response file if your vendor returns response files that are encrypted. Before encrypting files, you need to specify the request and response encryption type in the EncryptionResources.properties file.

This file is located in the path: C:\Program Files\Portal Software\VoucherAdministrationCenter\encrypt.jar.

About Managing Vouchers

After vouchers are created, you assign them to customer accounts by using Customer Center. See information about topping up accounts in the Customer Center Help.

You can search for a single voucher, multiple vouchers or brand accounts and then modify the voucher's state, expiration date, or brand attributes. You can also transfer the amount from the voucher to the customer's account.

About Voucher Device States

Voucher devices have the following device states:

When you process a vendor response file, you create voucher devices in the database. The device state of the vouchers is set to New.
In Customer Center, when an account is created and assigned a voucher, the device state is set to Used.
If an account is inactive or if an amount is transferred from a voucher device to customer's account, the device state is Used.
When the voucher is used up or expires, the device state is set to Expired.

Voucher devices have the following states:

1 = New
2 = Used
3 = Expired

The voucher states are represented with its related number in Voucher Administration Center.

About Managing Vouchers in a Branded System

When you log in to Voucher Administration Center, your login associates you with a brand. When you create and process an order, you can assign the order to the login brand, or any sub-brand. All vouchers in the order are also associated with the same brand.

Important:

Use Voucher Administration Center to update the brand of a device or an order when their state is New.

For information about branding, see "About Branding" in BRM Managing Customers.

Managing Vouchers in a Multischema System

If you manage vouchers in a multischema system:

In a multischema environment that is not brand enabled, you can create vouchers only in the database schema that you are logged in to.
If you log in as a brand host administrator and select Brand Host as the brand to create an order, you can create orders only in the schema that you logged in to. If you select any other brand, the order is created in the schema that hosts the selected brand.
You cannot change the brand of a voucher to a brand that is hosted in a different schema from the schema that the current brand is hosted in. For example, if a voucher belonging to Brand A is in schema 0.0.0.1, you cannot change the voucher to Brand B if Brand B is in schema 0.0.0.2.
When searching for vouchers or orders, if you log in as a brand host administrator and you select the top-level brand without including sub-brands in the search criteria, the search results include only vouchers or orders from the schema you logged in to.

Managing Expired Vouchers

If a voucher is not used, it expires. You must use the pin_voucher_expiration utility to change the state of the vouchers to Expired.

Note:

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

Use the following command to run the pin_voucher_expiration utility:

pin_voucher_expiration [-v] [-d]

For more information, see "pin_voucher_expiration".

About Voucher Customization Options

You can use policy opcodes to customize how vouchers are created and managed. See "Voucher Manager FM Standard Opcodes" in BRM Developer's Reference.

You can choose to encrypt the vendor request file and decrypt the vendor response file if your vendor returns response files that are encrypted. See "About Request and Response File Encryption".

Getting Information about Voucher Usage

You can get information about voucher inventory and status by running the Voucher Management reports. See "Voucher Manager Reports" in BRM Reports.

How Voucher Association Works

PCM_OP_VOUCHER_ASSOCIATE_VOUCHER calls PCM_OP_DEVICE_ASSOCIATE to perform these operations:

Calculate the balance impacts of purchasing the deal linked to the voucher device (/device/voucher object).
Associate a voucher device with an account or a service.

Before calling the device association opcode, this opcode uses the voucher device ID and PIN specified in the input flist to find the voucher device POID. It passes this POID to the device association opcode.

During voucher top-up operations, the PCM_OP_PYMT_TOPUP opcode calls the PCM_OP_PYMT_POL_VALID_VOUCHER policy opcode, which in turn calls PCM_OP_VOUCHER_ASSOCIATE_VOUCHER. PCM_OP_VOUCHER_ASSOCIATE_VOUCHER reformats the information it receives from the device association opcode so that it can be used by the top-up opcode. See "Performing Top-Ups with PCM_OP_PYMT_TOPUP" in BRM Configuring and Collecting Payments.

If the device association succeeds, PCM_OP_VOUCHER_ASSOCIATE_VOUCHER returns all currency and non-currency balance impacts of the voucher.

If the device association fails, the opcode returns an error in the error buffer.

PCM_OP_VOUCHER_ASSOCIATE_VOUCHER returns an error under these circumstances:

It cannot find a voucher device associated with the input ID and PIN in the BRM database.
The device cannot be associated with the account or service.

Customizing How Voucher Manager Manages Devices

Use the following opcodes to customize Voucher Manager devices:

PCM_OP_VOUCHER_POL_DEVICE_CREATE. See "Customizing Voucher Creation".
PCM_OP_PYMT_POL_VALID_VOUCHER. See "Customizing Voucher Validation".
PCM_OP_VOUCHER_POL_DEVICE_ASSOCIATE. See "Customizing Voucher Association".
PCM_OP_VOUCHER_POL_DEVICE_SET_ATTR. See "Customizing Voucher/Service Association".
PCM_OP_VOUCHER_POL_DEVICE_SET_BRAND. See "Setting the Brand for a Voucher".

Customizing Voucher Creation

PCM_OP_VOUCHER_POL_DEVICE_CREATE validates a device during device creation. For example, this policy opcode verifies that the numbers have the correct number of digits and use the proper syntax. It also verifies that the voucher does not already exist in the database.

You can customize this opcode to change the validation rules for creating voucher devices.

This opcode is called by PCM_OP_DEVICE_CREATE when creating a voucher device.

PCM_OP_VOUCHER_POL_DEVICE_CREATE returns the same values that are in the input flist. Some values might be reformatted, for example, extra spaces might be deleted.

This opcode returns an error when any of the values are not valid or when the voucher already exists in the database.

Customizing Voucher Validation

BRM uses the PCM_OP_PYMT_POL_VALID_VOUCHER policy opcode to validate vouchers. By default, this policy opcode interacts with Voucher Manager. If you use a third-party voucher management system, you must customize this policy opcode to work with that system. Vouchers are generally used for top-ups and prepayments only.

PCM_OP_PYMT_POL_VALID_VOUCHER is called by PCM_OP_PYMT_TOPUP during voucher top-up operations. To interact with a voucher management system, this policy opcode calls PCM_OP_VOUCHER_ASSOCIATE_VOUCHER. See "Performing Top-Ups with PCM_OP_PYMT_TOPUP" in BRM Configuring and Collecting Payments.

Customizing Voucher Association

PCM_OP_VOUCHER_POL_DEVICE_ASSOCIATE calculates the balance impacts of associating a voucher device (/device/voucher object) with an account or a service.

This policy opcode is called by the PCM_OP_DEVICE_ASSOCIATE opcode as follows:

To retrieve the balance impacts but not the information that enables PCM_OP_DEVICE_ASSOCIATE to associate the voucher with an account or a service, it is called with the PCM_OPFLG_CALC_ONLY flag on (calculation-only mode).
To retrieve the balance impacts and the information that enables PCM_OP_DEVICE_ASSOCIATE to associate the voucher with an account or a service, it is called with the PCM_OPFLG_CALC_ONLY flag off.

If the voucher is not expired, PCM_OP_VOUCHER_POL_DEVICE_ASSOCIATE calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to calculate the currency and non-currency balance impacts of the deal linked to the voucher.

Note:

Whether the PCM_OPFLG_CALC_ONLY flag is on or off, this policy opcode always calls PCM_OP_SUBSCRIPTION_PURCHASE in calculation-only mode. During top-up operations, this enables PCM_OP_PYMT_TOPUP to perform the actual balance impacts.

In addition, when called with the PCM_OPFLG_CALC_ONLY flag off, PCM_OP_VOUCHER_POL_DEVICE_ASSOCIATE calls PCM_OP_DEVICE_SET_STATE to update the voucher device status as follows:

If the voucher expiration date is passed, updates it from new to expired.
If the voucher is not expired, updates it from new to used.

If successful, PCM_OP_VOUCHER_POL_DEVICE_ASSOCIATE returns the following information:

Balance impacts of purchasing the deal linked to the voucher device
Validity dates of the resources associated with the affected balances

PCM_OP_VOUCHER_POL_DEVICE_ASSOCIATE returns an error in the following cases:

The device and the account or service are not in the same brand.
The voucher PIN specified in the input flist is not in the BRM database.
The specified voucher is expired.
The specified voucher is used.

Customizing Voucher/Service Association

PCM_OP_VOUCHER_POL_DEVICE_SET_ATTR ensures that the voucher card number (PIN_FLD_DEVICE_ID) cannot be changed during a device update. It validates a deal object available in the database if the deal object is changed.

You can customize this opcode to change how vouchers are associated with services.

This opcode is called by PCM_OP_DEVICE_SET_ATTR when updating a voucher card device.

PCM_OP_VOUCHER_POL_DEVICE_SET_ATTR returns an error if an attempt is made to change voucher pin or device ID, and when a deal object is changed.

Setting the Brand for a Voucher

PCM_OP_VOUCHER_POL_DEVICE_SET_BRAND validates that the voucher device state is New, when changing the voucher brand.

You can customize this opcode to change how vouchers can be associated with brands.

This opcode returns an error if the device state is not New.

Customizing How Voucher Manager Manages Orders

Use the following opcodes to customize Voucher Manager orders:

PCM_OP_VOUCHER_POL_ORDER_CREATE. See "Customizing Order Creation".
PCM_OP_VOUCHER_POL_ORDER_ASSOCIATE. See "Customizing Order Association".
PCM_OP_VOUCHER_POL_ORDER_SET_ATTR. See "Customizing Order Attributes".
PCM_OP_VOUCHER_POL_ORDER_SET_BRAND. See "Setting the Brand for an Order".
PCM_OP_VOUCHER_POL_ORDER_PROCESS. See "Canceling Orders".
PCM_OP_VOUCHER_POL_ORDER_DELETE. See "Deleting Orders".

Customizing Order Creation

PCM_OP_VOUCHER_POL_ORDER_CREATE validates the information in the input flist before an order object is created.

Validation consists of:

Checking for duplicate serial numbers.
Verifying the quantity ordered.

When calculating the quantity of vouchers within each order the following formula is applied:

Quantity = batch quantity * package quantity * total batches

Note:
* indicates multiplication.
Checking that the quantity is same as the quantity specified in the order.
Checking for the deal object existence.

You can customize this opcode to change the validation rules for creating /order/voucher objects.

This policy opcode is called by PCM_OP_ORDER_POL_CREATE when the /order/voucher object is created.

If any of the checks fail, this opcode returns an error message and logs an error in the CM pinlog file, indicating the reason for the failure. The /order/voucher object creation is terminated.

Customizing Order Association

PCM_OP_VOUCHER_POL_ORDER_ASSOCIATE ensures that a sub-order cannot be associated or disassociated with the master order when the order state is not New.

You can customize this opcode to change any validation for voucher order association.

This policy opcode is called by PCM_OP_ORDER_POL_ASSOCIATE when associating or disassociating a sub-order with the master order at account creation.

If the opcode is successful:

In case of association, the device is associated with the account or service and the device state is set to Assigned.
In case of disassociation, the device is disassociated with the account or service and the device state is set to Unchanged.

This opcode returns an error when you associate or disassociate a sub-order with the master order when the order state is not New.

Customizing Order Attributes

PCM_OP_VOUCHER_POL_ORDER_SET_ATTR validates the new values passed into the input flist before an order is modified.

This policy opcode is called by PCM_OP_ORDER_POL_SET_ATTR when updating the attributes and description of the /order/voucher object.

This policy opcode verifies that:

The order has not yet been sent to the vendor.
The modified serial number has no duplicate number in the database.
The order quantity is correct.

When calculating the quantity of vouchers within each order the following formula is applied:

Quantity = batch quantity * package quantity * total batches

Note:
* indicates multiplication.
The order is not modified when it is in the Received or Canceled state.

During validation, if it is found that the order was not yet sent to the vendor, the values are validated and updated with the new values passed in.

During validation, if it is found that the order has been sent to the vendor, updating or modifying the order is not allowed.

Setting the Brand for an Order

PCM_OP_VOUCHER_POL_ORDER_SET_BRAND ensures that the brand of an order cannot be changed when the order state is in Request or Partial Receive.

This policy opcode is called by PCM_OP_ORDER_POL_SET_BRAND when changing the brand association of an /order/voucher object.

This opcode returns an error message if a change is attempted on the order in Received or Partial Receive state.

Canceling Orders

PCM_OP_VOUCHER_POL_ORDER_PROCESS reads the status of an order using the order POID and terminates the processing of the order if the order state is Cancel.

A request file is sent to the relevant vendor and the vendor returns a vendor response file. The PCM_OP_ORDER_POL_PROCESS calls this opcode while processing the vendor response files.

Deleting Orders

PCM_OP_VOUCHER_POL_ORDER_DELETE ensures that an order cannot be deleted when the order is in the Received or Partial Receive state.

This policy opcode is called by PCM_OP_ORDER_POL_DELETE when deleting an order.

If deletion is attempted on the order object in Request or Partial Receive state, this opcode returns an error.