6 Accessing Configuration Files and Objects in Custom Code
Learn how to access pin.conf files and /config/business_params objects in your custom Oracle Communications Billing and Revenue Management (BRM) code.
Topics in this document:
Accessing pin.conf Files in Custom Code
You can use the PCM C++ PinConf class to enable your code to read values from a pin.conf file. For example, this code is from the policy source file fm_rate_pol_tax_loc.c. This code gets the value of the customer's tax locale from the Connection Manager (CM) pin.conf file:
/***********************************************************
* Look up the ISP city from pin.conf
***********************************************************/
pin_conf("fm_rate_pol", "provider_loc", PIN_FLDT_STR,
(caddr_t *)&locale, &perr);
The entry in the pin.conf file looks like this:
#======================================================================
# provider_loc
#
# City, state, ZIP code, and country where you provide services to
# your customers.
#
# This information is used to determine tax rates.
#======================================================================
- fm_rate_pol provider_loc Cupertino, CA 95014 USA
In the following example, this code in the fm_subscription_pol_spec_cancel.c policy source code file gets a value (0 or 1) from an entry in the CM pin.conf file:
/* Find all charge offers without a provisioning tag; cancel and
* delete charge offer from table.
*/
if (pin_conf_keep_cancelled_products_or_discounts == 0){
PIN_FLIST_FLD_SET(p_arrayp, PIN_FLD_ACTION,
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_DELETE, ebufp);
} else {
PIN_FLIST_FLD_SET(p_arrayp, PIN_FLD_ACTION,
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ONLY, ebufp);
}
The following example shows the entry in the pin.conf file.
#========================================================================
# keep_cancelled_products_or_discounts
#
# Specifies whether to keep canceled charge offers and discount offers
# associated with a specified account.
#
# The value for this entry can be one of the following:
#
# 1 = (Default) Deletes the canceled charge offer (/purchased_product [# object) or discount offer (/purchased_discount object) by using
# PCM_OP_DELETE_OBJ.
#
# 0 = Keeps the canceled /purchased_product or /purchased_discount object
# and sets its STATUS field to PIN_PRODUCT_STATUS_CANCELLED or
# PIN_DISCOUNT_STATUS_CANCELLED respectively.
#
#========================================================================
- fm_subscription_pol keep_cancelled_products_or_discounts 1
In addition to retrieving a value from a pin.conf file, you can hard code a default value that is used if the pin.conf entry is not present.
For information about the PinConf class, see "Accessing Configuration Values by Using pin.conf".
Using /config/business_params Objects
You can customize BRM by adding new business parameters to control various aspects of BRM operations and calling these business parameters from policy opcodes. You can also add completely new business parameter classes to BRM.
Adding and Loading New Parameters
Adding parameters is useful if you are customizing existing functionality; for example, to expand the criteria used to determine whether a payment should be suspended. To do this, you customize PCM_OP_PYMT_POL_VALIDATE_PAYMENT, the policy opcode that validates payments, to filter any payments below a specified amount.
For added flexibility, you may also want the ability to turn off this filter at certain times. One way to do this is to add a parameter to the /config/business_params object for the ar parameter class and have PYMT_POL_VALIDATE_PAYMENT check that parameter.
To implement the /config/business_params part of this process, you create a new parameter that you enable or disable depending on whether you want to filter payments below a specified amount so that these payments do not get suspended. This parameter will be called payment_suspense_amount_filter in the /config/business_params object and PaymentSuspenseAmntFilter in the supporting XML file set. You add the parameter as follows:
-
Modify the bus_params_AR.xsd file in the BRM_home/sys/data/config/ directory to add the new parameter. (BRM_home is the directory in which the BRM server software is installed.)
<xs:element name="PaymentSuspenseAmntFilter" type="switch"> <xs:annotation> <xs:documentation xml:lang="en">Enable/Disable filtering of payment suspense based on payment amount. The parameter values can be 0 (disabled) or 1 (enabled). The default is 0 (disabled).</xs:documentation> </xs:annotation> </xs:element>
-
Modify the bus_params_AR.xsl file in the BRM_home/sys/data/config/ directory to add the new parameter:
<xsl:template match="bc:PaymentSuspenseAmntFilter"> <xsl:element name="Param"> <xsl:element name="Name"> <xsl:text>payment_suspense_amount_filter</xsl:text> </xsl:element> <xsl:element name="Desc"> Enable/Disable filtering of payment suspense based on payment amount. The parameter values can be 0 (disabled) or 1 (enabled). The default is 0(disabled). </xsl:element> <xsl:element name="Type">INT</xsl:element> <xsl:element name="Value"> <xsl:choose> <xsl:when test="text() = 'enabled'"> <xsl:text>1</xsl:text> </xsl:when> <xsl:otherwise> <xsl:text>0</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:element> </xsl:element> </xsl:template>
-
Modify the bus_params_to_AR.xsl file in the BRM_home/sys/data/config/ directory to add the new parameter:
<xsl:when test="$name = 'payment_suspense_amount_filter'"> <xsl:element name="PaymentSuspenseAmntFilter"> <xsl:choose> <xsl:when test="$value = '1'"> <xsl:text>enabled</xsl:text> </xsl:when> <xsl:when test="$value = '0'"> <xsl:text>disabled</xsl:text> </xsl:when> </xsl:choose> </xsl:element> </xsl:when>
-
Use the pin_bus_params utility to retrieve the ar instance of the /config/business_params object:
pin_bus_params -r BusParamsAR bus_params_AR.xml -
Modify the resulting XML file to add the new parameter:
<PaymentSuspenseAmntFilter>disabled</PaymentSuspenseAmntFilter>
-
Use the pin_bus_params utility to load the object from the modified XML file:
pin_bus_params bus_params_AR.xml
For information on using the pin_bus_params utility, see "pin_bus_params".
Adding and Loading New Parameter Classes
You might need to add parameter classes when you create BRM features or customize existing functionality that has no associated parameter class.
Note:
You can determine if BRM has a parameter class for a certain functionality by looking at the support files. For example, bus_params_AR.xml and bus_params_billing.xml indicate that there are parameter classes for accounts receivable and billing. Support files for parameter classes are located in BRM_home/xsd.
To create a parameter class, you create the following files:
-
XML file: bus_params_parameter_class_name.xml: Contains the parameter settings from the /config/business_params object for the parameter class. Parameter settings in this file are loaded into the object by using the pin_bus_params utility. This file is located in BRM_home/sys/data/config.
-
XSD file: bus_params_parameter_class_name.xsd: Validates the contents of the bus_params_parameter_class_name.xml file when loading the object. This file is located in BRM_home/xsd.
-
XSL file: bus_params_parameter_class_name.xsl: Translates the contents of the bus_params_parameter_class_name.xml file into the correct format for the /config/business_params object. The pin_bus_params utility calls this file when loading the object. This file is located in BRM_home/xsd.
-
XML translation file: bus_params_to_parameter_class_name.xsl: Translates the contents of the /config/business_params object into XML format during object retrieval. This file is located in BRM_home/xsd.
For example, if you used custom policy opcodes to create a rewards tracking application, you could use a business parameter to switch between tracking frequent flier miles and tracking minutes. To do so, you would create the following:
-
A parameter class. In the /config/business_params object, the class would be named rewards. In the XML files, the class would be named BusParamsRewards.
-
A business parameter named RewardsTracking.To track miles, the option would be set to 0, to track minutes, it would be set to 1.
This business parameter would be named rewards-tracking in the /config/business_params object. The policy opcode would use the value of rewards-tracking.
To support the new parameter class and business parameter, you would create these files:
-
bus_params_rewards.xml
-
bus_params_rewards.xsd
-
bus_params_rewards.xsl
-
bus_params_to_rewards.xsl
To create these files:
-
Copy one of the bus_params_parameter_class_name.xsd sample files in BRM_home/xsd and save it as bus_params_rewards.xsd. Modify the file as follows:
<?xml version="1.0" encoding="UTF-8" ?> <xs:schema targetNamespace="http://www.portal.com/schemas/BusinessConfig" xmlns:businessConfig="http://www.portal.com/schemas/ BusinessConfig" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:annotation> <xs:documentation xml:lang="en" </xs:documentation> </xs:annotation> <xs:complexType name="BusParamsRewardsType"> <xs:sequence> <xs:element name="RewardsTracking" type="switch"> <xs:annotation> <xs:documentation xml:lang="en"> The reward to track. The parameter values can be 0 (Miles) or 1 (Minutes). The default is 1 (Minutes). </xs:documentation> </xs:annotation> <xs:simpleType name="rewardtrack"> <xs:restriction base="xs:string"> <xs:enumeration value="Miles" /> <xs:enumeration value="Minutes" /> <xs:whiteSpace value="collapse" /> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> </xs:complexType> </xs:schema>
-
Copy one of the bus_params_parameter_class_name.xsl sample files in BRM_home/xsd and save it as bus_params_rewards.xsl. Modify the file as follows:
<?xml version="1.0" encoding="UTF-8" ?> <xsl:stylesheet version="1.0" xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:bc="http://www.portal.com/schemas/BusinessConfig" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" exclude-result-prefixes="bc"> <xsl:output method="xml" indent="yes" /> <xsl:template match="/"> <BusinessConfiguration xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/ BusinessConfig business_configuration.xsd"> <BusParamConfiguration> <BusParamConfigurationList> <ParamClass desc="Business logic parameters for Reward Tracking" name="rewards-tracking"> <xsl:apply-templates select="/bc:BusinessConfiguration/ bc:BusParamConfigurationClass/ bc:BusParamsRewardsType/bc:*" /> </ParamClass> </BusParamConfigurationList> </BusParamConfiguration> </BusinessConfiguration> </xsl:template> <xsl:template match="bc:RewardsTracking"> <xsl:element name="Param"> <xsl:element name="Name"> <xsl:text>rewards-tracking</xsl:text> </xsl:element> <xsl:element name="Desc"> The reward to track. The parameter values can be 0 (Miles) or 1 (Minutes). The default is 1 (Minutes). </xsl:element> <xsl:element name="Type">INT</xsl:element> <xsl:element name="Value"> <xsl:choose> <xsl:when test="text() = 'Minutes'"> <xsl:text>1</xsl:text> </xsl:when> <xsl:otherwise> <xsl:text>0</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
-
Copy one of the bus_params_to_parameter_class_name.xsl sample files in BRM_home/xsd and save it as bus_params_to_rewards.xsl. Modify the file as follows:
<?xml version="1.0" encoding="UTF-8" ?> <xsl:stylesheet version="1.0" xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:bc="http://www.portal.com/schemas/BusinessConfig" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" exclude-result-prefixes="bc"> <xsl:output method="xml" indent="yes" /> <xsl:template match="/"> <BusinessConfiguration xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/ BusinessConfig business_configuration.xsd"> <BusParamConfigurationClass> <BusParamsRewards> <xsl:apply-templates select="/bc:BusinessConfiguration/ bc:BusParamConfiguration/bc:BusParamConfigurationList/ bc:ParamClass/bc:Param" /> </BusParamsRewards> </BusParamConfigurationClass> </BusinessConfiguration> </xsl:template> <xsl:template match="//bc:Param"> <xsl:variable name="name"> <xsl:value-of select="bc:Name/text()" /> </xsl:variable> <xsl:variable name="value"> <xsl:value-of select="bc:Value/text()" /> </xsl:variable> <xsl:choose> <xsl:when test="$name = 'rewards-tracking'"> <xsl:element name="RewardsTracking"> <xsl:choose> <xsl:when test="$value = '1'"> <xsl:text>Minutes</xsl:text> </xsl:when> <xsl:when test="$value = '0'"> <xsl:text>Miles</xsl:text> </xsl:when> </xsl:choose> </xsl:element> </xsl:when> </xsl:choose> </xsl:template> </xsl:stylesheet>
-
Copy one of the bus_params_parameter_class_name.xml sample files in BRM_home/sys/data/config and save it as bus_params_rewards.xml. Modify the file as follows:
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <BusinessConfiguration xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http:2www.portal.com/schemas/Business Config business_configuration.xsd"> <BusParamConfigurationClass> <BusParamsRewards> <RewardsTracking> Minutes </RewardsTracking> </BusParamsRewards> </BusParamConfigurationClass> </BusinessConfiguration>
-
Modify the bus_params_conf.xsd file in the BRM_home/xsd directory to add the new parameter class.
-
Add the following line to the schema location segment of the file:
<xs:include schemaLocation="bus_params_rewards.xsd"/>
-
Add the following line to the parameter class selection segment of the file:
<xs:element name="BusParamsRewards" type="BusParamsRewardsType"/>
-
-
Use the pin_bus_params utility to load the bus_params_rewards.xml file:
pin_bus_params bus_params_rewards.xml
When the new parameter class is created, and the business parameter is loaded, you can modify the custom policy opcode to look for the rewards-tracking value in the /config/business_params object.
Examples of Accessing Business Parameters in Custom Code
Opcodes read configuration values from /config/business_params objects to determine whether to run various functions. The following examples show how several BRM policy opcodes call values from /config/business_params objects.
Calling Business Parameters from PCM_OP_PYMT_POL_VALIDATE_PAYMENT
In its default implementation, the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode checks whether payment suspense management is enabled. If so, it places payments that could not be validated into suspense.
This code in the fm_pymt_pol_validate_payment.c policy source file determines whether to suspend payments that can't be validated. To make this determination, BRM calls the psiu_bparams_get_int() function and uses the psiu_business_params.h header file to retrieve specific parameters from the appropriate /config/business_params object. This information is used to determine whether payment suspense management is enabled (PSIU_BPARAMS_AR_PYMT_SUSPENSE_ENABLED):
/*************************************************************
* Check if Payment Suspense Management feature is enabled
*************************************************************/
pymt_suspense_flag = psiu_bparams_get_int(ctxp, PSIU_BPARAMS_AR_PARAMS,
PSIU_BPARAMS_AR_PYMT_SUSPENSE_ENABLE, ebufp);
if ((pymt_suspense_flag != PSIU_BPARAMS_AR_PYMT_SUSPENSE_ENABLED)&&
(pymt_suspense_flag != PSIU_BPARAMS_AR_PYMT_SUSPENSE_DISABLED))
{
pin_set_err(ebufp, PIN_ERRLOC_FM,
PIN_ERRCLASS_SYSTEM_DETERMINATE,
PIN_ERR_INVALID_CONF, 0, 0, 0);
PIN_ERR_LOG_EBUF(PIN_ERR_LEVEL_ERROR,
"bad param value for \"payment_suspense_enable\" in /config/business_params",
ebufp);
}
The segment that enables payment suspense management in the /config/business_params object looks like this:
0 PIN_FLD_PARAMS ARRAY [2] allocated 4, used 4 1 PIN_FLD_DESCR STR [0] "Enable/Disable payment suspense management. The parameter values can be 0 (disabled), 1 (enabled). Default is 0 (disabled)." 1 PIN_FLD_PARAM_NAME STR [0] "payment_suspense_enable" 1 PIN_FLD_PARAM_TYPE INT [0] 1 1 PIN_FLD_PARAM_VALUE STR [0] "1"
Calling Business Parameters from PCM_OP_BILL_POL_REVERSE_PAYMENT
In its default implementation, the PCM_OP_BILL_POL_REVERSE_PAYMENT policy opcode reverses payments applied to accounts that were written off; it does not reverse the payment if the write-off reversal was anything other than an account-level write-off.
This code in the fm_bill_pol_reverse_payment.c policy source code determines whether the write-off was at the account level. To make this determination, BRM calls the psiu_bparams_get_str() function and uses the psiu_business_params.h header file to retrieve specific parameters from the appropriate /config/business_params object. This information is used to determine whether write-off level is PSIU_BPARAMS_AR_PYMT_SUSPENSE_ENABLED. If so, it reverses the payment, again writing off the account:
/**************************************************************
* Verify if write off level set to "a" (account) in
* /config/business_params and Call PCM_OP_AR_ACCOUNT_WRITEOFF
**************************************************************/
psiu_bparams_get_str(ctxp, PSIU_BPARAMS_AR_PARAMS,
PSIU_BPARAMS_AR_WRITEOFF_LEVEL, writeoff_rev_level, 2, ebufp);
if ( status_flag && ( *status_flag == PIN_PYMT_WRITEOFF_SUCCESS ) &&
writeoff_rev_level &&
!strcmp(writeoff_rev_level, PIN_WRITEOFF_REV_LEVEL_ACCOUNT) )
{
i_flistp = PIN_FLIST_CREATE(ebufp);
vp = PIN_FLIST_FLD_GET(in_flistp, PIN_FLD_POID, 0, ebufp);
PIN_FLIST_FLD_SET(i_flistp, PIN_FLD_POID, vp, ebufp);
vp = PIN_FLIST_FLD_GET(in_flistp, PIN_FLD_PROGRAM_NAME, 0, ebufp);
PIN_FLIST_FLD_SET(i_flistp, PIN_FLD_PROGRAM_NAME, vp, ebufp);
vp = PIN_FLIST_FLD_GET(in_flistp, PIN_FLD_START_T, 1, ebufp);
if (vp)
{
PIN_FLIST_FLD_SET(i_flistp, PIN_FLD_START_T,
(void *) vp, ebufp);
}The segment that determines the write-off level in the /config/business_params object looks like this:
0 PIN_FLD_PARAMS ARRAY [2] allocated 4, used 4 1 PIN_FLD_DESCR STR [0] "Selection of level of writeoff to be tracked for the purpose of writeoff reversal. Values can be a(Account), b(Bill), i(Item), *(Any)." 1 PIN_FLD_PARAM_NAME STR [0] "writeoff_level" 1 PIN_FLD_PARAM_TYPE INT [0] 5 1 PIN_FLD_PARAM_VALUE STR [0] "a"