Implementing a new service (CDMA) in BRM

Invoice Number(Bill no) Formating

Here I'm presenting few guidelines to customize the invoice number format.

The out of the box format for the invoice number is :
Default Invoice : B1-BILLNO, e.g. B1-1234

We will take the case to customized Invoice number in the following format :
Customized Invoice Number : [ACCOUNT_POID]-BILLNO, e.g. 0000098976-1234
Where account_poid = 98976

For implementing the above change, we need to do the following steps :
1]. Customize the policy opcode : PCM_OP_BILL_POL_SPEC_BILLNO opcode needs modification to read sequence id(poid) from account object POID and replace B1 from default invoice number with the sequence id.
  To customize the PCM_OP_BILL_POL_SPEC_BILLNO, need to edit fm_bill_pol_spec_billno()  function of fm_bill_pol_spec_billno.c

fm_bill_pol_spec_billno(
{
    /*****************************************
    * Set the BILL_NO field according to poid
    *****************************************/
    vp = PIN_FLIST_FLD_GET(b_flistp,PIN_FLD_BILL_NO,1,ebufp);
    if((vp == (void *)NULL || (strlen((char *)vp) <= 0)) { // START OF IF BLOCK
        ............
        ............
        poid_db = PIN_POID_GET_DB(pdp);
        poid_id = PIN_POID_GET_ID(pdp);
        business_param_invoice_sequence_id_lt = psiu_bparams_get_int(ctxp, PSIU_BPARAMS_INVOICING_PARAMS,PSIU_BPARAMS_LENGHT_OF_SEQUENCE_ID,ebufp);
        printf(%s is the bill no", billno);
        sprintf(billno,"%llu",poid_id);
        /*start sequence */
        PIN_ERR_LOG_MSG(PIN_ERR_LEVEL_DEBUG,"--billno and poid--");
        PIN_ERR_LOG_MSG(PIN_ERR_LEVEL_DEBUG,billno);
        PIN_ERR_LOG_MSG(PIN_ERR_LEVEL_DEBUG,poid_id);
        PIN_FLIST_FLD_SET(b_flistp,PIN_FLD_BILL_NO,(void *)billno,ebufp);
   }//END OF IF BLOCK
   *out_flistpp = b_flistp;
    return;
}

Defaults for billing

 Here are some billing related important parameters and their default/OOB behavior. 

Business decision	Default behavior	How to customize
Set the default billing type to open item  accounting or balance forward accounting.	Balance forward accounting.	Change the actg_type entry  in the CM configuration file.  See Setting the default billing  type.  To customize the source code,  see  PCM_OP_CUST_POL_PREP_BILLINFO.
Set the default  accounting day to a  specific day of the  month, or to the day  that the account  was created.	The day that the account was created. For example, if a customer registers on the 15th, the accounting for that customer is done on the 15th. By default, if the account was created on day 29 - 31, the accounting day is the 1st of the next month. You can change this to be able to use any day of the month.	To set the default accounting  day of month, change the  actg_dom entry in the CM  configuration file.
Set the default number  of accounting cycles  in a billing cycle. The billing cycle  must be a  whole-number multiple  of accounting cycles.	Monthly billing (one accounting cycle per billing cycle).	Change the bill_when  entry in the CM  configuration file (pin.conf).
Specify the   system currency.	US dollars	You must set the system  currency when you  install Portal.
Specify the  default account  currency for  new accounts.	US dollars	Change the currency entry  in the CM  configuration file.
Specify whether to  create a long cycle  or a short cycle  when creating an  account or changing  the billing date.	If the short accounting cycle is 15 days or greater, create a short cycle. If the short accounting cycle is less than 15 days, create a long cycle.	Customize the  PCM_OP_CUST_POL_PREP_BILLINFO  source code.
Specify a numbering  scheme for bills.	Creates the bill number B-sequence number, for example, “B-81”.	Customize the  PCM_OP_BILL_POL_SPEC_BILLNO  source code.
Change the cutoff  time for billing,  accounting, and  promotion  start times. For example,  if your cutoff time  is 10:00:00 a.m.,  any events that take  place after 10:00:00 a.m.  on that date will  be included in the  next billing run.	The cutoff time is midnight.	Edit the /config/business_params  object.
Bill sponsor group  member accounts.	Sponsor group member accounts are not billed.	Change the billing_flow_sponsorship  and billing_flow_discount  parameters in /config /business_params object.
Change the number of  days to delay billing.	Billing is not delayed.	Change the   config_billing_delay  entry in the CM   configuration file (pin.conf) and the  pin_billd configuration file.
Change how  proration is calculated: The number of days in the cycle. The number of days in the month.	Number of days in the cycle.	Change the use_number_of_days_in_month  entry in the CM configuration file(pin.conf).
Align the purchase,  cycle, usage start  and end times with  the accounting  cycle if you set  up products  with delayed  fees.	Start and end times are not aligned.	Change the cycle_delay_align entry in the  CM configuration file(pin.conf).

31 Day Billing in BRM

By default, the billing day of month (BDOM) can be set to any day between 1 and 28. If a customer signs up on 29th, 30th, or 31st, the BDOM gets set to the 1st. This is done because all months do not have these days. This can result in a large number of customers being billed on the 1st of the month.

This default setting can be changed to support billing on all days of the month. For example, if you create a customer account on the 29th, the billing day is set to the 29th instead of the 1st. 

Setting the alternate billing day of month

If your customers’ billing day of month (BDOM) is the 29th, 30th, or 31st, for the months that do not have these days, you can configure whether billing should be run on the last day for the same month (set to back option) or the first day of the next month (set to forward option). By default, the BDOM is set to the 1st day of the next month.

For example, if a customer registers on March 31st:

• The set to back option sets the following billing dates:
• March 31
• April 30
• May 31

In this example, since April doesn’t have 31 days, the BDOM is on the last day of April.

• The set to forward option sets the following billing dates:
• March 31
• May 1
• May 31

In this example, since April doesn’t have 31 days, the BDOM is on the first day of the following month, May. 

Tip	To set the BDOM to always be the last day of the month, set it to 31 and use the set to back option.

Notes

Using these special days means that BDOM varies from month to month in a calendar year. The general ledger (GL) earned and unearned report accounts for the variation in the number of days in different accounting cycles. The cycle fees are charged in full regardless of how many days there are in a month. Cycle fees will be prorated only in special cases, for example, if you cancel a service in the middle of a month, or if you register in the middle of a month and your billing day of month is different from the date of account creation, the cycle fee may be prorated for such months.

 

Setting the 31 day billing feature

By default, billing does not use the special days 29th, 30th, and 31st. To use the special days, you must modify the init_objects.souce file before loading it into the database or modify the /config/fld_validate object using testnap.

By default, you can set the billing day of month (BDOM) to any day between 1 and 28. If your customer signs up on 29th, 30th, or 31st, the BDOM gets set to the 1st. This is done because all months do not have these days. This can result in a large number of customers being billed on the 1st of the month.
You can change this default setting to support billing on all days of the month. For example, if you create a customer account on the 29th, the billing day is set to the 29th instead of the 1st.

Setting the alternate billing day of month 

If your customers’ billing day of month (BDOM) is the 29th, 30th, or 31st, for the months that do not have these days, you can configure whether billing should be run on the last day for the same month (set to back option) or the first day of the next month (set to forward option). By default, the BDOM is set to the 1st day of the next month.
For example, if a customer registers on March 31st:

• The set to back option sets the following billing dates:
• March 31
• April 30
• May 31

In this example, since April doesn’t have 31 days, the BDOM is on the last day of April.

• The set to forward option sets the following billing dates:
• March 31
• May 1
• May 31

In this example, since April doesn’t have 31 days, the BDOM is on the first day of the following month, May.

Tip	To set the BDOM to always be the last day of the month, set it to 31 and use the set to back option.

Notes

Using these special days means that BDOM varies from month to month in a calendar year. The general ledger (GL) earned and unearned report accounts for the variation in the number of days in different accounting cycles. The cycle fees are charged in full regardless of how many days there are in a month. Cycle fees will be prorated only in special cases, for example, if you cancel a service in the middle of a month, or if you register in the middle of a month and your billing day of month is different from the date of account creation, the cycle fee may be prorated for such months.

Setting the 31 day billing feature

By default, billing does not use the special days 29th, 30th, and 31st. To use the special days, you must modify the init_objects.souce file before loading it into the database or modify the /config/fld_validate object using testnap.

>> Switching to 31 day billing during BRM installation

Before loading the init_objects.source file, change the value of the PIN_FLD_MAXIMUM field from 28 to 31 in the /config/fld_validate object which has the "Actg_cycle" value in the PIN_FLD_NAME field as follows:

# /config/fld_validate  - Actg_cycle validation

<PCM_OP $PIN_OPNAME=$PIN_CONF_INIT_OPNAME; $PIN_OPFLAGS=$PIN_CONF_

INIT_OPFLAGS>

0 PIN_FLD_POID           POID [0] $PIN_CONF_DB_NO /config/fld_validate 606 0

0 PIN_FLD_DESCR           STR [0] "Field Validation"

0 PIN_FLD_HOSTNAME        STR [0] "-"

0 PIN_FLD_NAME            STR [0] "Actg_cycle"

0 PIN_FLD_PROGRAM_NAME    STR [0] "-"

0 PIN_FLD_VALIDATION           SUBSTRUCT [0]

1       PIN_FLD_FIELD_TYPE     INT [0] 2

1       PIN_FLD_MAXIMUM        NUM [0] 31

1       PIN_FLD_MINIMUM        NUM [0] 1

</PCM_OP>

>>   Switching to 31 day billing after you have installed BRM

To switch to 31 day billing after you have installed Portal, use the testnap utility to set the Forward or Back billing option in the /config/business_params object


In this example, PIN_FLD_MAXIMUM is set to 31 indicating that Portal will use 31 day billing:

0 PIN_FLD_POID           POID [0] 0.0.0.1 /config/fld_validate 606

0 PIN_FLD_VALIDATION     SUBSTRUCT [0]

1       PIN_FLD_MAXIMUM  DECIMAL [0] 31 

Setting the Forward and Back billing options

By default, the BDOM is set to the 1st day of the next month. If you use 31-day billing, you can choose to run billing on the last day for the same month (set to back option) or the first day of the next month (set to forward option).
You configure the BDOM by modifying a field in the billing class /config/business_params object created during Portal installation.
You modify the /config/business_params object by using the pin_bus_params utility.

To configure BDOM to be last day of the month or 1st day of the next month:

1. Use the following command to create an editable XML file for the BusParamsBilling parameter class:

pin_bus_params -r BusParamsBilling bus_params_billing.xml

This command creates the XML file named bus_params_billing.xml.out in your working directory. If you don’t want this file in your working directory, specify the full path as part of the file name.

2. Search the XML file for following line:

<MoveDayForward>firstDay</MoveDayForward> 

3. Change firstDay to lastDay.

4. Use the following command to load the change into the /config/business_params object:

pin_bus_params bus_params_billing.xml  

You should execute this command from the PIN_HOME/sys/data/config directory, which includes support files used by the utility.

5. Read the object with the testnap utility or the Object Browser to verify that all fields are correct.

6. Restart Connection Manager (CM).

7. For multiple databases, run the pin_multidb script with the -R CONFIG parameter.

      Switching to 31 day billing during BRM installation

Before loading the init_objects.source file, change the value of the PIN_FLD_MAXIMUM field from 28 to 31 in the /config/fld_validate object which has the "Actg_cycle" value in the PIN_FLD_NAME field as follows:

# /config/fld_validate  - Actg_cycle validation

<PCM_OP $PIN_OPNAME=$PIN_CONF_INIT_OPNAME; $PIN_OPFLAGS=$PIN_CONF_

INIT_OPFLAGS>

0 PIN_FLD_POID           POID [0] $PIN_CONF_DB_NO /config/fld_validate 606 0

0 PIN_FLD_DESCR           STR [0] "Field Validation"

0 PIN_FLD_HOSTNAME        STR [0] "-"

0 PIN_FLD_NAME            STR [0] "Actg_cycle"

0 PIN_FLD_PROGRAM_NAME    STR [0] "-"

0 PIN_FLD_VALIDATION           SUBSTRUCT [0]

1       PIN_FLD_FIELD_TYPE     INT [0] 2

1       PIN_FLD_MAXIMUM        NUM [0] 31

1       PIN_FLD_MINIMUM        NUM [0] 1

</PCM_OP>  

    Switching to 31 day billing after you have installed BRM

To switch to 31 day billing after you have installed Portal, use the testnap utility to set the Forward or Back billing option in the /config/business_params object


In this example, PIN_FLD_MAXIMUM is set to 31 indicating that Portal will use 31 day billing:

0 PIN_FLD_POID           POID [0] 0.0.0.1 /config/fld_validate 606

0 PIN_FLD_VALIDATION     SUBSTRUCT [0]

1       PIN_FLD_MAXIMUM  DECIMAL [0] 31 

Setting the Forward and Back billing options

By default, the BDOM is set to the 1st day of the next month. If you use 31-day billing, you can choose to run billing on the last day for the same month (set to back option) or the first day of the next month (set to forward option).
You configure the BDOM by modifying a field in the billing class /config/business_params object created during Portal installation.
You modify the /config/business_params object by using the pin_bus_params utility.

To configure BDOM to be last day of the month or 1st day of the next month:

1. Use the following command to create an editable XML file for the BusParamsBilling parameter class:

pin_bus_params -r BusParamsBilling bus_params_billing.xml  

This command creates the XML file named bus_params_billing.xml.out in your working directory. If you don’t want this file in your working directory, specify the full path as part of the file name.

2. Search the XML file for following line:

<MoveDayForward>firstDay</MoveDayForward> 

3. Change firstDay to lastDay.

4. Use the following command to load the change into the /config/business_params object:

pin_bus_params bus_params_billing.xml  

You should execute this command from the PIN_HOME/sys/data/config directory, which includes support files used by the utility.

5. Read the object with the testnap utility or the Object Browser to verify that all fields are correct.

6. Restart Connection Manager (CM).

7. For multiple databases, run the pin_multidb script with the -R CONFIG parameter.

31 Day Billing in BRM

Currency Conversion in realtime rating

During realtime rating, currency conversion is handled by the following opcodes:

• PCM_OP_BILL_CURRENCY_CONVERT_AMOUNTS converts the currency according to the conversion rate defined in the /config/currency/conversionrates object. You can set multiple time periods for conversion rates. See Changing currency conversion rates.

This opcode fails if the specified time is not within the time range or if the source or destination currency is invalid. The ERROR_NOT_FOUND error code is returned.

• PCM_OP_BILL_CURRENCY_QUERY_CONVERSION_RATES retrieves the conversion rates from the /config/currency/conversionrates object. This opcode is called by PCM_OP_BILL_CONVERT_AMOUNTS.

This opcode fails if no conversion rate is specified between the source and destination currency types. The ERROR_NOT_FOUND error code is returned.

Configuring product and deals synchronization !

Now, this one is required when you want to refresh the batch pipeline data for each new product and deal created. However, most of this can be found in the BRM official documentation, but the deal synchronization is little tricky and is not specified anywhere.

You need to do some configurations and some customizations for the synchronization to work for you. We will start with the configurations of the processes.

1). Configuring CM(connection manager) for synchronization


Edit the following parameters for synchronization in CM's pin.conf

Parameter Name	Recommended value and Comment
Enable_publish	- fm_publish enable_pulish 1
Em_pointer	- cm em_pointer ip <hostname> <eai_js pointer>
Em_group	- cm em_group publish PCM_OP_ PUBLISH_GEN_PAYLOAD
Log_price_change_event	- fm_price log_price_change_event 1
Dm_pointer(for dm_eai)	- cm dm_pointer 0.0.9.1 ip <hostname> <dm_eai port>
Dm_pointer(for dm_aq)	- cm dm_pointer 0.0.9.7 ip <hostname> <dm_aq port>
Dm_pointer (for dm_ifw_sync)	- cm dm_pointer 0.0.9.9 ip <hostname> <dm_ifw_sync port>

2). Configuring DM_EAI for synchronization


Edit the following parameters for synchronization in DM_EAI's pin.conf

Parameter Name	Recommended value and Comment
Plugin_name	- dm plugin_name ./plugin_xml${LIBRARYEXTENSION}
Dm_db_no	- dm dm_db_no 0.0.9.1 0
Dm_port	- dm dm_port <port>

3). Configuring EAI_JS for synchronization


Edit the following parameters for synchronization in the Infranet.properties/Infranet_eai.properties of EAI_JS

Parameter Name	Recommended value and Comment
server.portNr(both files)	<port no>
infranet.opcode.handler(both files)	infranet.opcode.handler.PUBLISH_GEN_PAYLOAD= com.portal.eai.PublishHandler
configFile(infranet.properties file)	infranet.eai.configFile = <xml file>
configFile(infranet_eai.properties file)	infranet.eai.configFile = <xml file>

4). Configuring DM_AQ for synchronization


Edit the following parameters for synchronization in the pin.conf properties file of DM_AQ

Parameter Name	Recommended value and Comment
Plugin_name	- dm plugin_name ./${LIBRARYPREFIX}plugin_aq10g${LIBRARYEXTENSION}
queue_map_file	- dm_aq queue_map_file ./aq_queuenames
Dm_port	- dm dm_port <port>

4). Configuring DM_AQ for synchronization


Edit the following parameters for synchronization in the pin.conf properties file of DM_AQ

Parameter Name	Recommended value and Comment
Plugin_name	- dm plugin_name ./${LIBRARYPREFIX}plugin_aq10g${LIBRARYEXTENSION}
queue_map_file	- dm_aq queue_map_file ./aq_queuenames
Dm_port	- dm dm_port <port>

In addition to editing pin.conf properties file of DM_AQ, you need to edit aq_queuenames. This step is optional and required only for synchronizing deals.

Parameter Name	Recommended value and Comment
Adding business event under AQ_QUEUE	AQ_QUEUE{    DealCreateorModify }

Following steps are optional and are required only for synchronizing deals

5). Configuring event notification

• Edit the pin_notify file and add the following property :

Parameter Name	Recommended value and Comment
Add an entry to the pin_notify latest	1301 0 /event/audit/price/deal

• Load pin_notify

           load_pin_notify pin_notify

6). Configuring business event (payloadconfig_crm_sync.xml) 

To publish business events for create or modify deal, include below given definitions under <EventDefs> in the payloadconfig_crm_sync.xml configuration file :

<DealCreateorModify Source="/deal" PinFld="PIN_FLD_EVENT_AUDIT" Tag="DealCreateorModify" StartEvent='/event/audit/price/deal">

<Attribute Tag="InstanceId" Value="Portal"/>

<Attribute Tag="xmlns" Value="http://www.portal.com/schemas/CRMSync"/>

<Attribute Tag="xmlns:xsi " Value="http://www.w3.org/2001/XMLSchema-instance"/>

<Attribute Tag="xsi:schemaLocation" Value="http://www.portal.com/schemas/CRMSync/DealCreateorModify.xsd"/>

<Search SearchFld="PIN_FLD_POID" SearchVal="PIN_FLD_OBJECT" SearchValFrom="PIN_FLD_EVENT_AUDIT"/>

<Field PinFld="PIN_FLD_POID" Tag="DealPoid"/>

<Field PinFld="PIN_FLD_NAME " Tag="Name"/>

<Field PinFld="PIN_FLD_DESCR" Tag="Description"/>

<Field PinFld="PIN_FLD_PERMITTED" Tag="ServiceType"/>

<Field PinFld="PIN_FLD_START_T" Tag="DealStartDate"/>

<Field PinFld="PIN_FLD_END_T" Tag="DealEndDate"/>

</DealCreateorModify>

7). Creating XSD for Business event defined above

Create DealCreateorModify.xsd under <PIN_HOME>/sys/eai_js/xsd

<?xml version="1.0"?>

<xs:schema elementFormDefault="qualified" targetNameSpace="http://www.portal.com/schemas/CRMSync"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns="http://www.portal.com/schemas/CRMSync">

            <xs:element name="DealCreateorModify">

               <xs:complexType>

                        <xs:sequence>

                                    <xs:element ref="DealPoid"/>

                                    <xs:element ref="DealName"/>

                                    <xs:element ref="DealDescr"/>

                                    <xs:element ref="ServiceType"/>

                                    <xs:element ref="DealStartDate"/>

                                    <xs:element ref="DealEndDate"/>

                        </xs:sequence>

                        <xs:attribute ref="InstanceId" use="required"/>

               </xs:complexType>

            </xs:element>

            <xs:element name="DealPoid" type="xs:string"/>

            <xs:element name="DealName" type="xs:string"/>

            <xs:element name="DealDescr" type="xs:string"/>

            <xs:element name="ServiceType" type="xs:string"/>

            <xs:element name="DealStartDate" type="xs:string"/>

            <xs:element name=" DealStartDate" type="xs:string"/>

            <xs:attribute name="InstanceId" type="xs:string"/>

</xs:schema>

8). Configuring Oracle AQ - Registering for Notification

     1. Execute PL/SQL block to create an agent "aq_queue_subscriber"

begin

    dbms_aqadm.add_subscriber('AQ_QUEUE',SYS.AQ$AGENT('aq_queue_subscribe,NULL,NULL));

end;

/

   2. If above script fails, then try the PL/SQL block below :

BEGIN

     dbms_aqadm.stop_queue('AQ_QUEUE');

    dbms_aqadm.drop_queue('AQ_QUEUE');

    dbms_aqadm.drop_queue_table('AQ_SYNC');

END;

/

BEGIN

        DBMS_AQADM.CREATE_QUEUE_TABLE(queue_table=>'AQ_SYNC',

                                                                                compatible=>'8.1',

                                                                               storage_clause=>'tablespace pin00 initrans 5 storage(initial 200k next 200k maxextents unlimited pctincrease 0)',

                                                                               queue_payload_type=>'pin_event_ty',

                                                                              sort_list=>'priority,enq_time',

                                                                             multiple_consumers=>'TRUE');

END;

/

BEGIN

                    DBMS_AQADM.CREATE_QUEUE(queue_name=>'AQ_QUEUE',

                                                                              retention_time=>0,

                                                                             retry_delay=>6,

                                                                            queue_table=>'AQ_SYNC');

END;

/

BEGIN

         dbms_aqadm.start_queue('AQ_QUEUE');

END;

/

    3. Skip this step if step 1 was successful, else after completing step 2 successfully execute step 1 to create an agent

   4. Register an URL, which will invoke an http url when a queue gets enqueued. Execute the PL/SQL block below :

Declare

            reginfo                         sys.aq$_reg_info;

            reg_list                                    sys.aq$_reg_info_list;

Begin

            reginfo :=

                                    sys.aq$_reg_info('AQ_QUEUE:aq_queue_subscriber', DBMS_AQ.NAMESPACE_AQ,'http://10.18.19.80:8001/productsync/index', HEXTORAW('FF'));

            reg_list :=

                                    sys.aq$_reg_info_list(reginfo);

                                    DBMS_AQ.REGISTER(reg_list,1);

            commit;

END;

/

9). Restart BRM services