Utility to move pin_virtual_time(mode 1) and execute pin_bill_day

It sounds like huh, why should I need a script for changing virtual time or executing pin_bill_day but it has utility. Specially for BRM testing, there are scenarios where the movement of time followed by execution of pin_bill_day and pin_ledger_report are required, e.g.
   - Testing of invalid (soft declined/hard declined) credit cards
   - Checking the monthly bill for a certain period of time
   - Accounting validation by looking at General Ledger(GL) reports of certain months
   - Checking the expiration of the non-currency date based resources valid for a year
   - and so on

So this script has the following modes of operation when you will execute it :

$> perl tbill.pl
Current time is : mode 1  1367341200  Tue Apr 30 10:00:00 2013
mode 1  1367341200  Tue Apr 30 10:00:00 2013
Select from the following :
        1. Increment time to next day
        2. Increment time to a date
        3. Move time to a date by incrementing one day at a time
        4. Move time to a date by incrementing one month at a time :
        5. Move time to a date by incrementing 15 days at a time
        Your Selection(1|2|3|4|5) :

 Option1 : Increment time to next day and execute pin_bill_day and pin_ledger_report
Option2 : Increment time to a particular date in future like some date after few months in the same year or next year
Option3 : Increment time to a date in future by executing pin_bill_day and pin_ledger_report on each day of that period
Option4 : Increment time to few months by moving one month at a time and executing pin_bill_day and pin_ledger_report each month
Option5 : Increment time to a date by moving 15 day at once and executing pin_bill_day and pin_ledger_report



Here is the link of the script :

Guidelines to write a new FM in BRM

Creating a new FM

Steps to create a new FM in a CM :

1. Define new opcodes
2. Write a function to implement the new opcode
3. Write a program to map opcodes to functions
4. Create a shared library on UNIX i.e. ".so" file
5. Configure the new FM as part of the CM

1. Defining new opcodes

You must define your custom opcodes, with their numbers, in a header file and execute parse_custom_ops_fields.pl on the file. parse_custom_ops_fields.pl creates an extension to the pcm_tbls.c file. Client applications use pcm_tbls.c to map a field or opcode to its number.

Portal opcodes and their numbers are defined in the ops/*.h files in the <BRM_HOME>/include directory.
To pass new opcodes from a client application to a new FM, use the PCM_OP macro.

To define a new opcode:
  a). Create a header file and define your new opcodes by using this format:
      #define    opcode_name_1    opcode_number_1

      For example, you might create a header file named my_opcodes.h with these definitions :

      #define MY_OP_SET_AGE     100001
      #define MY_OP_SET_LANGUAGE  100002

       Important: Numbers upto 100000 are reserved for use by BRM.


  b). Run the parse_custom_ops_fields.pl perl script by using this syntax:

       parse_custom_ops_fields.pl -L language -I input -O output -P java_package

 c). For the applications written in PCM C or PCM COM, create an entry using the following format in the pin.conf each application :
      - - ops_fields_extension_file ops_flds_ext

      Where ops_flds_ext is the file name and location of the memory-mapped extension file that was created by the parse_custom_ops_fields.pl script.
       Make sure that you included your header file both in the application that is calling the opcode and in the custom FM.


2. Writing a function to implement a new opcode 

     To implement a new opcode in BRM, you have to write a new function that calls the base system opcodes to access the DM. The new function then becomes part of the new FM shared library in UNIX.

     The new function you are implementing should conform to the PCM_OP calling convention.
     Use the PCM_OP_* reference pages as checklists and templates to determine what your custom function must implement. Pay particular attention to the input and output flists.

Important If you are adding a new function in the fm_utils module that can be called outside the module, add a prototype of that function in the fm_utils.h

3. Creating an opcode-to-function mapping file 

    You create a configuration program fm_*_config.c to map an opcode name to the function that implements it. This configuration file is read when a dynamic library is created, and the mapping information is stored in it.  When a parent CM is inititalized, it configures the opcode-function pairs into itself, and each child CM inherits the same configuration as its parent CM.

   The configuration program contains an array of struct cm_fm_config for each opcode and its corresponding function and the config function at the end.
   For a definition of this struct (cm_fm_config), see the cm_fm.h file in the BRM_SDK_HOME/include directory.
   The following example shows an opcode-to-function configuration file.

Important Include you ".h" file with your new custom opcodes

#ifndef lint
static  char    Sccs_id[] = "@(#) fm_custom_config.c 1.0 24 May 2011 %";
#endif
#include <stdio.h> /* for FILE * in pcm.h */
#include "ops/base.h"
#include "pcm.h"
#include "cm_fm.h"
#include "ops/my_header.h"

/*******************************************************************
* Opcodes handled by this FM.
*******************************************************************/
struct cm_fm_config my_config[] = {
/* opcode as a u_int, function name (as a string) */
{ MY_FIRST_OPCODE , "op_my_opcode" },
{ 0, (char *)0 }
};

void * my_config_func()
{
return ((void *) (my_config));
}


When the CM gets a MY_FIRST_OPCODE opcode through the PCM_OP call from a client application, the CM looks up at this table and calls the op_cust_create_acct() function.


4. Adding a new FM module to the CM configuration file 

The configuration file contain the names of the shared libraries that implement the base and custom opcodes. It also contains the names of the corresponding configuration files that contain the opcode-to-function mappings.

Use the entries for the system FMs in the default CM configuration file pin.conf in the BRM_HOME/sys/cm as an example to add your custom FM entries. For example, the typical entries for custom FMs look like:

- cm fm_module BRM_HOME/lib/my_fm.so my_config - pin

In this example, I'm assuming that the new dynamic library that implements the new custom FM my_fm.so is copied to BRM_HOME/lib directory. "my_config" is the name of the configuration implementation that contains the name-to-function mapping of the new custom OpCode.

5. Compiling and linking a custom FM

Use the libraries in the Portal_SDK_home/lib for linking.
Each custom FM must be created as a shared library on UNIX

Important classes in Oracle BRM

In BRM, account/customer related data such as names, addresses, profiles, current account balances, group charge sharing, and account hierarchy are stored. Plans/deals/products can be purchased by the customer which gets associated with their account. The customers can purchase one or more services like GSM/GPRS et.c. (in case the subscriber is a telecom subscriber).  Some of the key or most important BRM classes are:

/ACCOUNT :  This is one of the most important and key storable class of BRM that stores information about the customer. The customer information includes their contact info,status, locale and tax related information. Account class is mapped to account_t table and is uniquely identified by POID. Each account has a default balance group and is associated with the instances of billinfo, balance group,payment method, purchased products, purchased discounts and services.

/BALANCE_GROUP :  Stores the balance information for each currency and non-currency resources in an account . A balance group includes one or more sub-balances for each resource. The sub-balance contains the current amount, resource type, validity dates for the resource, rollover data, and sub-balance contributors. This storable class is mapped with the  bal_grp_t table in BRM database.

/BILL : This storable class contains the information for the bills generated for each customer based on the products they purchase or the usage they do. It includes information such as the amount due, amount adjusted, currency and bill number. A /bill object is created for each account that have a due at the beginning of a billing cycle. It contains information for the invoice and the billinfo object with which it is associated. It maps with the  bill_t  table in BRM database.

/BILLINFO: Stores all billing, payment method, accounting cycle, and hierarchy information necessary to bill an account. A default /billinfo object is created for every account. If the billinfo is subordinate, the /billinfo object points to the parent account and the parent account’s /billinfo object. It maps to billinfo_t table in BRM database.


/INVOICE: Stores a customer invoice and information about the invoice, such as the bill it is associated with. Each /bill object can have a corresponding /invoice object. It maps to invoice_t table in BRM database.

/ITEM: Created to bundle events, this table summarizes billable item activity by type. It maps to item_t table in BRM database. Rows in this table are added for each row in the BILL_T table.

/PAYINFO: Stores generic payment method information for an account. It maps to payinfo_t  table in BRM database.


/DEAL: Stores information about a deal.When you use Pricing Center and connect to the database, all /deal objects in the database are shown in Pricing Center. It maps to DEAL_T table in BRM database.


/PRODCUT: Stores the information for a single product. Maps to product_t table.


/DEVICE: Stores information about devices. There is a separate /device object for every device managed by BRM. Generic data applicable to all devices is stored in the parent /device object. Subclasses such as /device/num store information specific to a particular device type. It maps to device_t table in BRM database.


/PROFILE: Abstract class to support custom account information. To use a /profile object, always create a subclass. You can link an account to any number of /profile objects. Maps to profile_t table.


/EVENT : Abstract class to record system-initiated and user-initiated events. Event objects are related to a specific service or to an account. An event includes generic information such as start and end times as well the balance impacts that are incurred by the account due to this event. The /event object points to the account balance group that is impacted.Maps to event_t table in BRM database. The event class stores the event balance data in another table event_bal_impacts_t.


/PURCHASED_PRODUCT : Contains an entry for each product owned by an account at the time of conversion.Maps to purchased_product_t table in the BRM database.



/PURCHASED_DISCOUNT: Contains an entry for each discount owned by an account at the time of conversion.Maps to purchased_discount_t table in the BRM database.

/SERVICE : Stores generic service type information for accounts. There is one row in this table for each applicable service for each entry in ACCOUNT_T. In addition to a row in this table, a row must be created in the service type table, such as IP service or email. Maps to service_t table in the BRM database.


/CONFIG: Base class for configuration objects. Subclasses hold specific configuration information for various features, for example, /config/beid defines currency and non-currency resources. Maps to config_t  table.

Custom fields in BRM

Oracle Communications Billing and Revenue Management offers two methods for creating, editing and deleting custom fields and storable classes. One approach is by using Storable Class Editor, part of the Developer Center application, and the other is by using SDK opcodes.

This post will address manipulating custom fields with SDK opcodes.

Before beginning, one change needs to be made first: making the data dictionary writable. Here’s how to do it:

1. Open the DM Oracle configuration file ($BRM_HOME/sys/dm_oracle/pin.conf) in a text(e.g. vi) editor.

2. Enable field manipulation in the data dictionary, by setting the following entry to 1:-

      dm dd_write_enable_fields 1

Our objectives are as follows:

1. To create a custom field

2. To edit the custom field description

3. To delete the custom field from the database

4. To make the custom field available to BRM

1. Creating a New Custom Field

Creating a new custom field and committing it to the database can be accomplished with SDK opcodes or with a pin deploy utility. As developers know, SDK opcodes provide a more flexible way to create, edit, and delete custom fields at the development stage. The pin deploy utility, on the other hand, uses PODL (Portal Object Definition Language) to export and import  field and storable class definitions. This is more useful, especially at the administrative level, because the process can be streamlined by putting field definitions into source code management and thus lower any possibility of damaging the Oracle BRM production database data dictionary.

The following SDK opcodes can be used to manage field specifications:

i. PCM_OP_SDK_SET_FLD_SPECS – create or modify a field,

ii. PCM_OP_SDK_GET_FLD_SPECS – retrieve a field specs,

iii. PCM_OP_SDK_DEL_FLD_SPECS – delete a field.

To create a field, it’s necessary to write an input flist for PCM_OP_SDK_SET_FLD_SPECS opcode:

0 PIN_FLD_POID          POID [0] 0.0.0.1 /dd/fields 0 0

0 PIN_FLD_FIELD      ARRAY [0]

1    PIN_FLD_DESCR          STR [0] “custom field for holding a VAT number”

1    PIN_FLD_FIELD_NAME      STR [0] “C_FLD_VAT_NUMBER”

1    PIN_FLD_FIELD_NUM      ENUM [0] 10000

1    PIN_FLD_FIELD_TYPE      INT [0] 5

Now, verify that the field created exists in the database data dictionary by feeding the following input flist to PCM_OP_SDK_GET_FLD_SPECS opcode:

0 PIN_FLD_POID      POID [0] 0.0.0.1 /dd/objects 0 0

0 PIN_FLD_FIELD    ARRAY [0]

1    PIN_FLD_FIELD_NAME    STR [0] “C_FLD_VAT_NUMBER”

2. Editing the Custom Field Description

Now, having confirmed that the new custom field exists, the description can be altered by calling PCM_OP_SDK_SET_FLD_SPECS opcode with the following input flist:

0 PIN_FLD_POID          POID [0] 0.0.0.1 /dd/fields 0 0

0 PIN_FLD_FIELD      ARRAY [0]

1    PIN_FLD_DESCR          STR [0] “custom field – VAT number”

1    PIN_FLD_FIELD_NAME      STR [0] “C_FLD_VAT_NUMBER”

1    PIN_FLD_FIELD_NUM      ENUM [0] 10000

1    PIN_FLD_FIELD_TYPE      INT [0] 5

Again, the field’s specifications can be retrieved so as to verify that the change has been accomplished.

After that, delete the custom field from the database.

Finally, assume a mistake has been made, and it’s necessary to delete a field. Provide the following input flist to PCM_OP_SDK_DEL_FLD_SPECS opcode, deletes the field:

0 PIN_FLD_POID        POID [0] 0.0.0.1 /dd/fields 0 0

0 PIN_FLD_FIELD      ARRAY [0]

1    PIN_FLD_FIELD_NAME      STR [0] “C_FLD_VAT_NUMBER”

If the opcode for retrieving the field’s specifications returns an empty flist (only POID obj),then that signifies the field was not found in the database data dictionary.

3. Making the Custom Fields Available to BRM

Standard practice dictates that everything custom developed goes into the BRM_HOME/custom directory, and since, in this case, BRM_HOME/include/pin_flds.h, is being extended, a new custom header file BRM_HOME/custom/include/custom_flds.h. needs to be created.

Now, the new custom field can be introduced by appending the following line to custom_flds.h:

#define MY_CUSTOM_FLD PIN_MAKE_FLD(PIN_FLDT_STR, 10000)

The line above defines a custom field named “MY_CUSTOM_FLD” with data type “PIN_FLDT_STR” (STR stands for string) and unique identifier “10000″ (in regards to BRM_HOME/include/pin_flds.h).

Data types are static, and defined by the BRM version you are running; please see BRM_HOME/include/pcm.h for definitions.

Next, run the parse_custom_ops_fields.pl perl script on the custom_flds.h using this command:

$BRM_HOME/bin/parse_custom_ops_fields.pl -L pcmc -I custom_flds.h -O $BRM_HOME/custom/include/custom_mapping.m

And finally, include the following line to every pin.conf where it’s desired that these field be seen: –

- ops_fields_extension_file ${BRM_HOME}/custom/include/custom_mapping.m

NOTE: When introducing new functionalities using custom fields, it is necessary to include the custom_flds.h header file in the FMs that use these fields