This chapter describes how to implement a new business policy and how to change a default Oracle Communications Billing and Revenue Management (BRM) policy by using policy opcodes. It explains the difference between System Facilities Modules (FMs) and Policy FMs.
For a complete list of business policies implemented by default in BRM and how to change them, see "Implementation Defaults".
Note:
You can also change certain default implementations of business policies by using the policy configuration tools in Configuration Center or by changing entries in the Connection Manager (CM) configuration file.BRM functionality, such as billing and rating, is implemented by using FMs and a set of applications that rely on them. The FMs implement opcodes, each of which performs a specific function related to the business processes of its manager. See "FM Opcodes" for more information.
BRM uses two types of opcodes:
System opcodes
Policy opcodes
Many system opcodes have a corresponding policy opcode that allows you to customize functionality. For example, the PCM_OP_AR_REVERSE_WRITEOFF standard opcode calls the PCM_OP_AR_POL_REVERSE_WRITEOFF policy opcode, which you can customize.
From a technical perspective, System FMs and Policy FMs follow the same rules and are built with the same Application Programming Interfaces (APIs). However, they differ significantly in the types of functions they implement. Each System and Policy FM set has a corresponding header file, which must be included in applications that use an opcode from that FM set.
System FMs:
Define and implement the basic functionality.
Guarantee the integrity of all operations performed.
For example, the registration module includes an opcode in its System FM called PCM_OP_CUST_CREATE_CUSTOMER, which takes customer registration information and creates an account object in the database. A formal set of steps is followed, including preparing and validating all the fields, creating and initializing the account and service objects, purchasing the appropriate plans and deals, validating the credit card, and so on. These steps are carried out within a well-defined transactional model that guarantees the integrity of the resulting objects.
You cannot modify the default System FMs, but you can create new ones and configure them into BRM.
For information on creating a custom FM, see "Writing a Custom Facilities Module".
You use Policy FMs to implement your business policy decisions. System FMs use these policies to choose among a set of reasonable behaviors under a specific set of circumstances.
For example, the payment module includes an opcode in its Policy FM called PCM_OP_PYMT_POL_SPEC_VALIDATE, which determines whether a customer's payment information needs to be validated after events such as a new registration or a change to the customer's payment details. This policy opcode doesn't perform any of the actual work. It takes a description of the situation, makes the decision based on your business policy, and returns that decision to the System FM for execution.
Every policy opcode includes a default implementation already configured into BRM. If your business policies differ from the default implementation, you can implement custom policies and configure them into BRM. Because the business policies are separated into their own opcodes, you can easily customize the policies without affecting the underlying functionality of BRM.
Policy FMs consist of a number of opcodes that are implemented by using C functions, and these opcodes enable you to change the default behavior of BRM. For example, you can substitute customized opcodes for existing policy opcodes to validate Automatic Account Creation (AAC) information, create and check customer passwords, validate login names, and assign dynamic IP addresses.
Policy FM opcodes receive a set of situational details as input and return a business policy decision as output. In general, this decision is based on the input parameters, and the policy opcode does not call any additional opcodes or access the database. However, if the business behavior of your custom policy opcode requires executing other opcodes that access data in the database, you can implement them.
Policy FM opcodes can perform any of the actions supported by FMs while deriving the data the FMs return as input. For example, in addition to the parameters passed as input, customer information can be read from the database to drive the business decision. Or an external system, such as a credit rating bureau, can be accessed to provide additional validation of a new customer during registration.
Policy FM opcodes must conform to the standard BRM calling conventions. They receive parameters according to the input flist specification and are expected to return parameters according to the return flist specification. For detailed descriptions of the Policy FM opcodes, see the individual opcode descriptions.
Each policy opcode description explains the calling conventions and includes links to its input and output flist specifications, a detailed description of the functionality of the default implementation, and pointers to any configuration files that it uses.
Each opcode description also contains a link to the .c file that implements its behavior.
Important:
When you modify policy opcodes at the source code level, observe the transactional rules around the policy call. Because the System FMs that call the Policy FMs are responsible for the transactional integrity of BRM, they impose restrictions on certain policy opcodes. See the Transaction Handling section of the individual opcodes for details.You can change the default behavior of many BRM operations by using customized policy opcodes. You make your changes to the policy's .c file. Then, you compile and link this file with an updated Policy FM, which can be dynamically linked to any CM.
Policy opcodes are installed as executable binary files. In addition, most policy opcodes include source files that you can customize and compile. As of release 7.3, some policy opcodes do not include source files. In that case, you can create your own version of those policy opcodes.
In all cases, flist specs are provided in the documentation.
Note:
In some cases, some opcodes in a single Policy FM include source code and some do not.To create a custom version of the opcode:
Create a custom version of the opcode. Use the same name as the opcode supplied by BRM. For example, to create a customer version of the PCM_OP_ACT_POL_SCALE_MULTI_RUM_QUANTITIES opcode, create an opcode named PCM_OP_ACT_POL_SCALE_MULTI_RUM_QUANTITIES.
See the opcode flist spec documentation for guidance on optional and required fields.
Edit the fm_name_pol_config.c file.
For example, fm_gprs_aaa_pol_config.c.
Comment out the opcodes that you do not want to customize as shown in the following example:
struct cm_fm_config fm_gprs_aaa_pol_config[] = {
/* opcode (as an int), function name (as a string) */
{ PCM_OP_GPRS_AAA_POL_AUTHORIZE,
"op_gprs_aaa_pol_authorize" },
{ PCM_OP_GPRS_AAA_POL_SEARCH_SESSION,
"op_gprs_aaa_pol_search_session" },
{ PCM_OP_GPRS_AAA_POL_ACC_ON_OFF_SEARCH,
"op_gprs_aaa_pol_acc_on_off_search" },
{ PCM_OP_GPRS_AAA_POL_AUTHORIZE_PREP_INPUT,
"op_gprs_aaa_pol_authorize_prep_input" },
{ PCM_OP_GPRS_AAA_POL_REAUTHORIZE_PREP_INPUT,
"op_gprs_aaa_pol_reauthorize_prep_input" },
{ PCM_OP_GPRS_AAA_POL_UPDATE_ACCOUNTING_PREP_INPUT,
"op_gprs_aaa_pol_update_accounting_prep_input" },
{ PCM_OP_GPRS_AAA_POL_STOP_ACCOUNTING_PREP_INPUT, "op_gprs_aaa_pol_stop_accounting_prep_input" },
{ 0,(char *)0 }
If you comment out an opcode, the default functionality is used.
Run the Makefile provided with the opcode source. The Makefile creates a new policy library file called fm_name_pol_custom.so, which contains the custom policy. The entry of the custom source code must be made in the Makefile.
Open the CM pin.conf file and add an entry for the custom executable file. The entry must follow the entry for the default implementation. The CM reads the entries and implements the last entry it finds.
- cm fm_module fm_gsm_aaa_pol.so fm_gsm_aaa_pol_config - pin - cm fm_module fm_gsm_aaa_pol_custom.so fm_cust_gsm_aaa_custom_config - pin
To use the default implementation with your custom implementation:
Include multiple entries for the same opcode in the CM file.
Open CM pin.conf file and add the below CM pin.conf entry in the last line.
- cm fm_module ${PIN_HOME}/lib/fm_name_pol_custom${LIBRARYEXTENSION} fm_name_pol_custom_config - pin
where fm_name_pol_custom${LIBRARYEXTENSION} denotes the custom policy library name, and fm_name_pol_custom_config denotes the custom policy configuration structure name.
Save the CM pin.conf file, and restart the CM process.
The CM loads both implementations of the policy code, the default implementation and the custom implementation. However, by default, CM executes the implementation that is configured last in the CM pin.conf file.
Use the custom opcode to call the default implementation of the policy opcode by including the CM_FM_OP_PREV_IMPL or CM_FM_OP_PREV_IMPL_BY_REF macro in your custom opcode source code.
If you want to add some customization to the implementations and if you want to call the default implementation from the custom implementation, use one of the above functions to call the previous (default) implementation of the same policy opcode.
Run your custom implementation first, and then the default implementation, using the CM.
Note:
In case of the CM_FM_OP_PREV_IMPL macro, a local copy of the input flist is created to call the opcode. The local copy is destroyed after the called opcode is returned.
In case of the CM_FM_OP_PREV_IMPL_BY_REF macro, a copy of input flist is not created. The given input flist is passed to the opcode so that the called opcode uses the input flist as reference only and does not alter the data.
For information about the CM_FM_OP_PREV_IMPL and CM_FM_OP_PREV_IMPL_BY_REF macro, see the cm_fm.h file in the BRM_Home/include directory, where BRM_Home is the directory in which you installed BRM components.
A Policy FM consists of a set of opcodes and functions. The functions implement the opcodes. The functions are compiled and then linked into a shared library (the Policy FM).
For examples, see the .c source files for each opcode in BRM_SDK_Home/source/sys/fm_category_pol, where category is the name of the opcode category.
To create a new Policy FM:
Define the input and output flist specifications.
This is already done for you. Each policy opcode must conform to the input and output flist specifications referenced in the opcode reference document.
Write a function to implement your custom opcode.
To do this, modify a copy of the .c source file provided for the corresponding default policy opcode.
For example, to change the default behavior of the PCM_OP_CUST_POL_PREP_BILLINFO policy opcode, change the op_cust_pol_prep_billinfo function, which is contained in the fm_cust_pol_prep_billinfo.c file.
Create an entry in the configuration file to map the function to an opcode or if it is a new policy FM, create a configuration file to specify the opcode-to-function mapping.
For information on creating the file, see "Creating an Opcode-to-Function Mapping File".
All policy operations conform to the rules for application-level transactions.
See the Transaction Handling section of the individual opcodes for details.
If a read-write or read-only transaction is open when a policy operation is performed, all data read as part of the operation will be consistent with the state of the database when the transaction is opened. This guarantees that the data used by this operation is consistent with related data used by other operations in the transaction.
If this operation is called when a transaction is not already open, the operation is performed without transactional control.
Caution:
Policy operations must not modify storable object data.After you define or modify the policy opcodes, create a shared library for the new Policy FM by using the Makefile included in each Policy FM source directory.
Enter make to create the .so or .a file.
The shared library (.so on Solaris, Linux, and HP-UX IA64; and .a on AIX) for the Policy FM must be included in each CM where its functionality is needed. Whenever a new CM is started or restarted, the CM reads its configuration file and loads the listed System FMs and Policy FMs dynamically. For more information, see "Writing a Custom Facilities Module".
Configure the new FM as part of the applicable CMs by adding the new Policy FMs to the CM configuration file.
For information on the format of the configuration file entries, see the CM configuration file.