Oracle Billing Introduction

This document and the subsequent documents give a very high level overview of BRM system and customization of one aspect of the system. In order to get a deeper understanding of the all the concepts at a greater depth, it is recommended to refer to the BRM implementation guide which is provided with any version of the BRM product. The following material has been written taking BRM Documentation as a basis to reflect some custom changes made to Paymenetch engine.

Introduction:

Oracle Billing and Revenue Management (BRM) is a software product which provides a complete solution to generate, capture, collect, manage and analyze revenue activities for Cable, Media & Telecommunications companies and Internet Service Providers. Revenue generation is achieved by implementing complex price and service plans through Customer Management tools like Customer Center and Pricing Center. Revenue capture is implemented by rating the usage of network services by Customers using a complex rating engine. Revenue collection is implemented by generating invoices, billing customer usage and providing a means to collect payments through online transactions or check/cash deposits, and updating the payment information to General Ledger. Revenue analysis is implemented by generating reports which in turn reflect revenue leaks, areas of improvement, statistical analysis displaying various parameters for price plans and assists in maximizing revenue generation.

Service creation is done by installing applications like AAA Manger and RADIUS Manager which capture events generated by customers. Service usage is charged by defining a Rate Plan. Customers select Price Lists when they get registered by a Customer Service Representative by Customer Center Application. A combination of Price Lists form a Deal and a combination of Deals form a Plan. CSRs capture user details like personal details, type of service requested, rate plan and payment information. All this data is reflected back into the BRM Database. Customer Center also manages customer account information, invoices, payment type and authorization. Rating of service usage is done based on the rate plans selected by the customer. Rating is a continuous process. When a customer initiates a session, he is charged for the service usage for that session. This charging process is called Rating. Rating measures the event in time duration units, apply charge to it and add this charge to the current account balance of the customer. Rating can be real-time where records are charged whenever they get created, or batch rating where charges are applied to the records at some period of the day. Pipeline Manger handles rating process in the BRM system. Billing is the process which is performed by collecting the accumulated charges, of a customer; add promotions, incentives, pending amounts and taxes to the accumulated charges. Technically billing is carried on by run ‘pin’ utilities. It can be done bimonthly, monthly or of any duration based on the Rate Plan selected. Also the process of billing involves in the generation of invoice. BRM captures Accounts Receivable in bill items and usage items.

Basic Flow:
BRM works on a four tier architecture consisting of the following tiers:

1. Application Tier
2. Connection Management Tier
3. Data Management Tier
4. Physical Database/Validation tier

Client GUI applications which try to directly interact with a user like Customer Center, Developer Center, Pricing Center, Payment Center form the Application Tier. The processing of the client applications is done by passing the requests received to the Connection Management Tier, which in turn passes on the request to specific Data Management Tier. Entities in the Data Management Tier speak to the actual physical databases or validation/processing engines. Retrieved data is sent back to the client application which waits for a response. Communication between various tiers is done through TCP/IP connections.

Applications speak to application specific Facilities Modules (FM). The FMs are actually a part of Connection Manager (CM) which is the primary component of the Connection Management Tier and acts as the co-ordination & control entity of the BRM System as a whole. FMs capture data received form the client application and perform sanity checks on the data. They can be dynamically linked to a CM and start along with the CM. Since FMs are associated with a CM they can access the configuration file of the CM. Although this is the fundamental architecture between an application and the CM External Modules (EM), Front End and Back End processes can also be present based on the Client Application. EMs are a set of opcodes which run separately from the CM but perform similar functions as FMs. So they need to be started and stopped manually. CM process runs as a daemon and spawns a child process whenever a client application requests a connection. There should be at least one CM running on a BRM System. A configuration file specific to the CM is executed whenever the system is started. Requests are routed by the CM ,if an entry for that type of request is present in the configuration file, to a DM. To get hold of a CM one can even install a Connection Manger Master Process, which allots a CM by mentioning the machine name and port number where the allotted CM is currently executing. Data Mangers (DM) form the components of Data Management Tier. A specific DM exists for every different kind of database / credit card validation process. A DM has a set of front-end and back-end processes. The front end processes accept requests from the CM. The back-end process spawns single thread processes for each transaction and these transactions are performed on the database. The backend process translates the application requests into a language the database can understand which basically would be SQL queries for BRM, Tax databases and credit card processors. The backend modules speaking to a database or credit card processing system are called Storage Managers (SM). Dedicated daemon DM processes exist for each data access system. All the DMs have an entry in the CM configuration file. So when an application sends a request it is redirected as per the entries in this file. Each DM has a configuration file which lists out various parameters about the data base / processing service for which it has been configured. When a request for this DM comes from the CM , the entries in this file are read and executed. The CM configuration file should contain the entries to identify each DM that is configured in the BRM System. Each DM is allocated a shared memory space. This space is used for transaction processing of incoming application requests.

The FMs, EMs, SMs, the configuration file entries in the CM and DM can be customized and configured. On can develop custom code to construct a custom DM by taking into account of the considerations for its shared memory space and functions for entry, processing and exit.

Technical Details:
The following subsections give a birds eye view of the technical details involved in implementing various modules of BRM and how they speak with each other. A simplified diagram of the whole system is given below.

Configuration files are the access points of various modules of the BRM system. A set of configuration file entries are given below.

#==============================================================
# dm_dd_dm_pointer
#==============================================================
- cm dm_pointer 0.0.1.2 ip IBIZOCA 12810

#==============================================================
# dm_fusa_dm_pointer
#==============================================================
- cm dm_pointer 0.0.1.1 ip IBIZOCA 12810

#==============================================================
# cc_dm_pointer
#==============================================================
#- cm dm_pointer 0.0.1.4 ip IBIZOCA 14810

#==============================================================
# dm_generic_dm_pointer
#==============================================================
- cm dm_pointer 0.0.0.20 ip IBIZOCA 14950
- fm_bill cc_db 0.0.0.20 /_cc_db 0

#==============================================================
# dm_provisioning_pointer
#
# Specifies where to find the Provisioning Data Manager.
#==============================================================
- cm dm_pointer 0.0.10.2 ip IBIZOCA 11990 # dm_prov_telco

Each module has a configuration file under the name pin.conf to specify the connection parameters required for the entities above and below the current module to mainatin sequentail flow of operation. The keywords cm, dm, fm right beside ‘-‘ sign in any configuration file are actually executables and the keywords ‘dm_pointer’, ‘fm_bill’ are corresponding options/arguments in this executable. Whenever the pin.conf files are read, these options are actually executed in the sequence mentioned in the file. So, if one has to customize a CM or DM, a custom code mentioning what the options/arguments are, has to be written.

Data and Database BRM operates data in the language of flists. Flists are a set of defined pointers to corresponding data. The retrieval and storage of data is done only once from the database. An opcode acts on this data and reflects the updated values in an flist. This flist becomes the input flist of the next opcode in the sequence. In order to perform a request , a sequence of opcodes have to defined by default or programmatically so that a favorable result can be obtained. Field types such as arrays, decimals, substructures, enum, err, int, binstr, string buf and poid have been defined by the BRM system. A sample flist is shown below.

0	PIN_FLD_POID	POID [0] 0.0.0.1 /account 14606 11
0	PIN_FLD_PROGRAM_NAME	STR [0] "CC Validation"
0	PIN_FLD_END_T	TSTAMP [0] (1279061630) Tue Jul 13 17:53:50 2010
0	PIN_FLD_START_T	TSTAMP [0] (1279061630) Tue Jul 13 17:53:50 2010
0	PIN_FLD_BATCH_INFO	ARRAY [0] allocated 20, used 2
1	PIN_FLD_CHANNEL_ID	INT [0] 1
1	PIN_FLD_POID_VAL	POID [0] 0.0.0.20 /payment 1000 0
0	PIN_FLD_CHARGES	ARRAY [0] allocated 20, used 9
1	PIN_FLD_ACCOUNT_OBJ	POID [0] 0.0.0.1 /account 14606 11
1	PIN_FLD_ACCOUNT_NO	STR [0] "0.0.0.1-14606"
1	PIN_FLD_COMMAND	ENUM [0] 1
1	PIN_FLD_PAY_TYPE	ENUM [0] 10003
1	PIN_FLD_MERCHANT	STR [0] "ibizsoft"
1	PIN_FLD_CURRENCY	INT [0] 840
1	PIN_FLD_AMOUNT	DECIMAL [0] 10
1	PIN_FLD_TRANS_ID	STR [0] "T1,39,0"
1	PIN_FLD_PAYINFO	ARRAY [0] allocated 20, used 1
2	PIN_FLD_CC_INFO	ARRAY [0] allocated 20, used 9
3	PIN_FLD_SECURITY_ID	STR [0] "234"
3	PIN_FLD_CITY	STR [0] "New York"
3	PIN_FLD_STATE	STR [0] "NY"
3	PIN_FLD_ZIP	STR [0] "10112"
3	PIN_FLD_COUNTRY	STR [0] "USA"
3	PIN_FLD_NAME	STR [0] "Michael  Chricton"
3	PIN_FLD_ADDRESS	STR [0] "40 Rockefellar Plaza"
3	PIN_FLD_DEBIT_EXP	STR [0] "XXXX"
3	PIN_FLD_DEBIT_NUM	STR [0] "XXXX"

Explanation:

0

PIN_FLD_POID

POID [0] 0.0.0.1 /account 14606 11

• 0 stands for the depth of the current field.
• PIN_FLD_POID is the name of the field. There are standard field names although one write custom fields based on opcodes that act on this data.
• POID defines the type of the field.
• 0.0.0.1 is the database number which is specific to this type of field. There can integers, decimals, enums at this location.
• /account 14606 11 specifies /account storable class and this flist conatins object number 14606 with revision number 11. When custom objects are built for testing the object ID should be greater than 1000. Revision number is not to be mentioned. It is handled by BRM.

The following operations summarize the manipulation macros in the PIN library. The format of the macro would be PIN_FLIST__

PUT Operation : Adds data to flists overwriting the existing pointers.
SET Operation : Adds data to flists by replacing existing data
TAKE Operation : Removes pointer form a piece of data from one flistand assigns it to a different flist.
GET Operation : Copies pointers to data of one flist to a different flist.
DESTROY, DESTROY_EX : Destroys the mentioned flist.
Examples : – PIN_FLIST_TAKE, PIN_FLIST_GET, PIN_FLIST_SET

Data is stored in the form of storable classes in BRM database. A hierarchical structure is followed in a similar to inheritance concept in object oriented programming. Base classes are defined in the BRM system by default. Extended classes are those subclasses which inherit the fields of the previous class. Unextended  classes inherit all the fields of its base class but do not have fields of their own. 
The representation of storable classes is given as under:
/account
/config/ach
/service/ip
/admin_action/suspended_usage/writeoff/

Storable Classes can be custom created. Although the following fields for every class are mandatory.
PIN_FLD_POID
PIN_FLD_NAME,
PIN_FLD_CREATED_T
PIN_FLD_MOD_T
PIN_FLD_READ_ACCESS
PIN_FLD_WRITE_ACCESS

Opcodes  are data management/manipulation entities of a BRM system. They are atomic. One cannot go a level below opcodes to manage data. A set of opcodes can be customizable, while the others cannot be changed. In order to understand or customize opcodes one needs to know both the PIN libraries and PCM libraries. PIN library opcodes deal with the manipulation of flists, POIDs, fields and strings. PCM library opcodes deal with the context and connection management of interacting modules and the database. A set of opcodes which perform a similar function or operations in sequence are declared in specific header files. While customization one has to include these header files, so that opcodes can be called  and function code can be written. All opcodes work on flists. There would be mandatory fields in the flist which are needed so that the opcode may produce a correct result.

            PCM opcodes have ‘PCM_OP_’as a suffix and they are called by this suffix. They specify a context pointer, input flist, output flist, an error buffer pointer and the opcode name as parameters. Base opcodes are utilized to perform creating and manipulating objects,  and to search objects based on a search criteria which itself is given as an input flist . FM opcodes implement functions for what the FM is defined for. They are very specific to the function. They start with ‘fm_’ and only those opcodes that contain ‘pol’ in there are customizable.

Developer Center is a GUI based interface option to view opcodes, run them based on an input flist and view storable classes & corresponding objects in the form of flists.  It can be installed as a Client Application or at the back end server. At the backend , along with Portal Development Kit package, it acts as a rich tool to develop/customize BRM modules right from the opcode level. The components of Development Center are:

• Storable Class Editor is used to define, view, display storable classes and fields.
• Opcode Work Bench  is used to test opcodes as defined in the PCM API library which would deal in manipulating objects in the BRM database. These kind of opcodes start with ‘PCM_OP_’.
• Universal event Mapper defines the templates to load events from a log file into the database.
• Object Browser  hierarchically displays all the storable objects that have been created in the BRM database along with their version numbers.

As of this document and purpose, Opcode Work Bench and Object Browser have been utilized significantly. Following are the screenshots and explanations of these tools.

The Opcode Work Bench conatins a buffer area where in one can paste the input flist and run an opcode form the text box. If all the mandatory fields in the input flist are valid, then an  output flist is displayed  in the box below the input fist buffer.

Input flist :

0	PIN_FLD_POID	POID [0] 0.0.0.1 /account 14606 11
0	PIN_FLD_END_T	TSTAMP [0] (1279061630) 13/07/2010 17:53:50:000 PM
0	PIN_FLD_OP_CORRELATION_ID	STR [0] "1:Divyang-Ibiz:UnknownProgramName:0:AWT-EventQueue-0:3:1280442647:0"
0	PIN_FLD_PROGRAM_NAME	STR [0] "CC Validation"
0	PIN_FLD_START_T	TSTAMP [0] (1279061630) 13/07/2010 17:53:50:000 PM
0	PIN_FLD_BATCH_INFO	ARRAY [0] allocated 2, used 2
1	PIN_FLD_CHANNEL_ID	INT [0] 1
1	PIN_FLD_POID_VAL	POID [0] 0.0.0.20 /payment 1000 0
0	PIN_FLD_CHARGES	ARRAY [0] allocated 9, used 9
1	PIN_FLD_ACCOUNT_NO	STR [0] "0.0.0.1-14606"
1	PIN_FLD_ACCOUNT_OBJ	POID [0] 0.0.0.1 /account 14606 11
1	PIN_FLD_AMOUNT	DECIMAL [0] 10
1	PIN_FLD_COMMAND	ENUM [0] 1
1	PIN_FLD_CURRENCY	INT [0] 840
1	PIN_FLD_MERCHANT	STR [0] "ibizsoft"
1	PIN_FLD_PAY_TYPE	ENUM [0] 10003
1	PIN_FLD_TRANS_ID	STR [0] "T1,39,0"
1	PIN_FLD_PAYINFO	ARRAY [0] allocated 1, used 1
2	PIN_FLD_CC_INFO	ARRAY [0] allocated 9, used 9
3	PIN_FLD_ADDRESS	STR [0] "40 Rockefellar Plaza"
3	PIN_FLD_CITY	STR [0] "New York"
3	PIN_FLD_COUNTRY	STR [0] "USA"
3	PIN_FLD_DEBIT_EXP	STR [0] "XXXX"
3	PIN_FLD_DEBIT_NUM	STR [0] "XXXX"
3	PIN_FLD_NAME	STR [0] "Michael  Chricton"
3	PIN_FLD_ADDRESS	STR [0] "40 Rockefellar Plaza"
3	PIN_FLD_SECURITY_ID	STR [0] "234"
3	PIN_FLD_STATE	STR [0] "NY"
3	PIN_FLD_ZIP	STR [0] "10112"

The resultant flist is :

0	PIN_FLD_POID	POID [0] 0.0.0.1 /account 14606 11
0	PIN_FLD_CREATED_T	TSTAMP [0] (1275494827) 02/06/2010 11:07:07:000 AM
0	PIN_FLD_MOD_T	TSTAMP [0] (1278458137) 06/07/2010 18:15:37:000 PM
0	PIN_FLD_READ_ACCESS	STR [0] "L"
0	PIN_FLD_WRITE_ACCESS	STR [0] "L"
0	PIN_FLD_AAC_ACCESS	STR [0] ""
0	PIN_FLD_AAC_PACKAGE	STR [0] ""
0	PIN_FLD_AAC_PROMO_CODE	STR [0] ""
0	PIN_FLD_AAC_SERIAL_NUM	STR [0] ""
0	PIN_FLD_AAC_SOURCE	STR [0] ""
0	PIN_FLD_AAC_VENDOR	STR [0] ""
0	PIN_FLD_ACCESS_CODE1	STR [0] ""
0	PIN_FLD_ACCESS_CODE2	STR [0] ""
0	PIN_FLD_ACCOUNT_NO	STR [0] "0.0.0.1-14606"
0	PIN_FLD_ACCOUNT_TAG	STR [0] ""
0	PIN_FLD_ACCOUNT_TYPE	ENUM [0] 1
0	PIN_FLD_ATTRIBUTE	INT [0] 0
0	PIN_FLD_BAL_GRP_OBJ	POID [0] 0.0.0.1 /balance_group 16142 0
0	PIN_FLD_BRAND_OBJ	POID [0] 0.0.0.1 /account 1 0
0	PIN_FLD_BUSINESS_TYPE	ENUM [0] 1
0	PIN_FLD_CLOSE_WHEN_T	TSTAMP [0] (0) 31/12/1969 18:00:00:000 PM
0	PIN_FLD_CURRENCY	INT [0] 840
0	PIN_FLD_CURRENCY_SECONDARY	INT [0] 0
0	PIN_FLD_CUSTOMER_SEGMENT_LIST	STR [0] ""
0	PIN_FLD_EFFECTIVE_T	TSTAMP [0] (1275494827) 02/06/2010 11:07:07:000 AM
0	PIN_FLD_GL_SEGMENT	STR [0] "."
0	PIN_FLD_GROUP_OBJ	POID [0] 0.0.0.0  0 0
0	PIN_FLD_INCORPORATED_FLAG	ENUM [0] 0
0	PIN_FLD_INTERNAL_NOTES	BUF [0] flag/size/offset 0×00 0 0 data:
0	PIN_FLD_ITEM_POID_LIST	STR [0] "0.0.0.1|/item/misc 26971 0"
0	PIN_FLD_LASTSTAT_CMNT	STR [0] ""
0	PIN_FLD_LAST_STATUS_T	TSTAMP [0] (1275494827) 02/06/2010 11:07:07:000 AM
0	PIN_FLD_LINEAGE	STR [0] "/0.0.0.1:14606/"
0	PIN_FLD_LOCALE	STR [0] "en_US"
0	PIN_FLD_NAME	STR [0] "PIN Account Object"
0	PIN_FLD_NEXT_ITEM_POID_LIST	STR [0] ""
0	PIN_FLD_OBJECT_CACHE_TYPE	ENUM [0] 0
0	PIN_FLD_RESIDENCE_FLAG	ENUM [0] 0
0	PIN_FLD_STATUS	ENUM [0] 10100
0	PIN_FLD_STATUS_FLAGS	INT [0] 0
0	PIN_FLD_TIMEZONE_ID	STR [0] ""
0	PIN_FLD_VAT_CERT	STR [0] ""
0	PIN_FLD_NAMEINFO	ARRAY [1] allocated 20, used 20
1	PIN_FLD_ADDRESS	STR [0] "40 Rockefellar Plaza"
1	PIN_FLD_CANON_COMPANY	STR [0] ""
1	PIN_FLD_CANON_COUNTRY	STR [0] "US"
1	PIN_FLD_CITY	STR [0] "New York"
1	PIN_FLD_COMPANY	STR [0] ""
1	PIN_FLD_CONTACT_TYPE	STR [0] "Account holder"
1	PIN_FLD_COUNTRY	STR [0] "USA"
1	PIN_FLD_EMAIL_ADDR	STR [0] "michael.chricton@xyz.com"
1	PIN_FLD_FIRST_CANON	STR [0] "michael"
1	PIN_FLD_FIRST_NAME	STR [0] "Michael "
1	PIN_FLD_LAST_CANON	STR [0] "chricton"
1	PIN_FLD_LAST_NAME	STR [0] "chricton"
1	PIN_FLD_MIDDLE_CANON	STR [0] ""
1	PIN_FLD_MIDDLE_NAME	STR [0] ""
1	PIN_FLD_SALUTATION	STR [0] "Mr."
1	PIN_FLD_SERVICE_OBJ	POID [0] 0.0.0.0  0 0
1	PIN_FLD_STATE	STR [0] "NY"
1	PIN_FLD_TITLE	STR [0] ""
1	PIN_FLD_ZIP	STR [0] "10112"
1	PIN_FLD_PHONES	ARRAY [0] allocated 2, used 2
2	PIN_FLD_PHONE	STR [0] "212-2347409"
2	PIN_FLD_TYPE	ENUM [0] 1
1	PIN_FLD_PHONES	ARRAY [1] allocated 2, used 2
2	PIN_FLD_PHONE	STR [0] "212-8662478"
2	PIN_FLD_TYPE	ENUM [0] 2

Another view of the Opcode Work Bench is shown below

The Object Browser displays all the storable classes in a drop down box as shown below. The Portal Object ID of each object for a class is displayed in the ‘Buffer 1’ area. When a POID is selected, the flist corresponding to that POID is displayed in the ‘Output flist’ area.