Invoice Opcode Workflows

15 Invoice Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) invoice opcode workflows.

Topics in this document:

Opcodes Described in This Chapter

Table 15-1 lists the opcodes described in this chapter.

Caution:

Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
Do not use SQL commands to change data in the database. Always use the API.

Table 15-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_POL_SPEC_EVENT_CACHE	Including Custom Data in Invoices Specifying Event Fields to Cache for Invoicing
PCM_OP_AR_GET_ALLOCATED_AR_ITEMS	How Invoices Are Generated
PCM_OP_BILL_MAKE_BILL	How Trial Invoicing Works for Hierarchical Bill Units in BI Publisher 11g
PCM_OP_BILL_MAKE_TRIAL_BILL	Generating Trial Invoices
PCM_OP_CUST_COMMIT_CUSTOMER	Defining the Invoice Type
PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE	About Associating Bill Units with a BI Publisher Invoice and Report About the /associated_bus_profile Object
PCM_OP_CUST_CREATE_BILLINFO	About Associating Bill Units with a BI Publisher Invoice and Report About the /associated_bus_profile Object
PCM_OP_CUST_POL_PREP_PAYINFO	Setting the Default Payment Due Date
PCM_OP_CUST_SET_ASSOCIATED_BUS_PROFILE	About Associating Bill Units with a BI Publisher Invoice and Report
PCM_OP_CUST_SET_PAYINFO	Defining the Invoice Type
PCM_OP_INV_DECODE_INVOICE_DATA	Decoding Cached Event Data for Invoicing Creating Custom Search Templates
PCM_OP_INV_FORMAT_INVOICE	How Invoices Are Formatted Customizing the Invoice Format by Using an XSL Style Sheet
PCM_OP_INV_MAKE_INVOICE	Making Invoices Defining the Invoice Type How Invoices Are Formatted
PCM_OP_INV_MAKE_INVOICE	How Invoices Are Generated Customizing Invoice Search Operations Creating Custom Search Templates Configuring Error Checking for Customized Invoicing Generating Trial Invoices
PCM_OP_INV_POL_FORMAT_INVOICE	Customizing the Format for Printed Invoices
PCM_OP_INV_POL_FORMAT_INVOICE	Including Custom Data in Invoices
PCM_OP_INV_POL_FORMAT_INVOICE_DOC1	Customizing the Format for DOC1 Invoices
PCM_OP_INV_POL_FORMAT_INVOICE_HTML	Customizing the Format for HTML Invoices Customizing the Layout of Bill Items in Invoices Customizing the Format for Printed Invoices Including the Time Zone in Invoices
PCM_OP_INV_POL_FORMAT_INVOICE_XML	Customizing the Format for XML Invoices
PCM_OP_INV_POL_FORMAT_INVOICE_XSLT	Customizing the Invoice Format by Using an XSL Style Sheet How Invoices Are Formatted Displaying an Invoice On Demand
PCM_OP_INV_POL_FORMAT_VIEW_INVOICE	Displaying Invoices How Invoices Are Formatted Customizing the Format for HTML Invoices Customizing the Format for XML Invoices Displaying an Invoice On Demand
PCM_OP_INV_POL_POST_MAKE_INVOICE	How Invoices Are Generated Customizing Invoice Search Operations Example: Generating Invoices Based on Event Types Configuring Error Checking for Customized Invoicing
PCM_OP_INV_POL_PREP_INVOICE	How Invoices Are Formatted Customizing the Layout of Bill Items in Invoices Customizing the Format for Printed Invoices
PCM_OP_INV_POL_PREP_INVOICE	Including Custom Data in Invoices
PCM_OP_INV_POL_PREP_INVOICE	Changing the Trial Billing Watermark
PCM_OP_INV_POL_PREP_INVOICE	How Trial Invoicing Works for Hierarchical Bill Units in BI Publisher 11g
PCM_OP_INV_POL_SELECT	Decoding Cached Event Data for Invoicing How Invoices Are Generated Customizing Invoice Search Operations Creating Custom Search Templates Example: Generating Invoices Based on Event Types
PCM_OP_INV_VIEW_INVOICE	Displaying Invoices Displaying an Invoice On Demand
PCM_OP_PYMT_POL_PRE_COLLECT	Adding Soft Descriptors to Invoices

Setting the Default Payment Due Date

The default payment due date for invoice payments is 30 days from the billing date. To change the number of days, customize the PCM_OP_CUST_POL_PREP_PAYINFO policy opcode.

Making Invoices

PCM_OP_INV_MAKE_INVOICE creates an invoice for a specified (regular or corrective) bill object.

For regular invoices, PCM_OP_INV_MAKE_INVOICE does the following:

Uses the PIN_FLD_INV_DETAIL_FLAG value in the /payinfo object to determine whether to generate a detailed invoice or a summary invoice
Uses the invoicing threshold parameters in the /config/business_params object to determine whether the invoices of nonpaying bills in a bill unit (/billinfo object) hierarchy should be generated separately or consolidated into the invoice of the paying parent bill

PCM_OP_INV_MAKE_INVOICE is the initial opcode that gets called to create an invoice for a designated bill object.

PCM_OP_INV_MAKE_INVOICE identifies corrective bills by the entries PIN_OBJ_NAME_CORRECTIVE_BILL, PIN_OBJ_NAME_CORRECTIVE_BILL_NOW, and PIN_OBJ_NAME_CORRECTIVE_BILL_ON_DEMAND in the PIN_FLD_NAME field in the bill object.

For corrective invoices, the default value for the type of corrective invoice (whether it is a Replacement Invoice or an Invoice Correction Letter and whether that document is a summary or in detail) is obtained from the PIN_FLD_INV_TYPE field from the /event/billing/corrective_bill object. For invoices in a bill unit hierarchy, the default setting is determined by the corresponding value in the /event/billing/corrective_bill object in the parent invoice.

If PIN_FLD_INV_FLAGS is present in the input flist when PCM_OP_INV_MAKE_INVOICE is called, the opcode discards the default value and uses the PIN_FLD_INV_FLAGS value from the input flist with the entries in the pin_inv.h file to arrive at the required type of corrective invoice.

The opcode retrieves the correction reason and previous bill number from the /event/billing/corrective_bill object and inserts them in the corrective invoice. It calls the fm_inv_get_previous_bill to retrieve the contents of the latest history_bills object.

Typically, you generate invoices automatically as part of running the pin_bill_day billing script. This script runs several utilities, including pin_inv_accts, the invoicing utility.

pin_inv_accts runs twice. In the first run, it performs the following tasks to handle bill unit hierarchies:

Searches for all bills that have reached the end of their billing cycle and for which invoices have not yet been generated.
Checks the nonpaying threshold values in the /config/business_params object to determine the maximum number of nonpaying child bill units that are allowed in the bill unit hierarchy.
For each /bill object retrieved, checks the PIN_FLD_AR_HIERARCHY_SIZE value to determine if it exceeds the threshold value.
If the threshold is exceeded, uses multiple threads to retrieve the nonpaying bill units and to generate an invoice for each one.

Note:

If bill suppression is enabled on an account with a paying parent bill unit and the nonpaying child bill unit threshold is exceeded, invoicing fails. This occurs because nonpaying bill units, which use the bill number of their paying parent bill unit's parent account, are generated even when billing for the parent account is suppressed. In such cases, they do not contain bill numbers, which invoices require. To exclude invoicing for these bills, run pin_inv_accts with the -skip_blank_billnos parameter. (Nonpaying bill units contain bill numbers only when their paying parent bill unit's parent accounts are billed.)

If no errors occur, pin_inv_accts runs a second time to generate invoices for parent accounts in hierarchies and for nonhierarchical accounts:
Searches for all bills that have reached the end of their billing cycle and for which invoices have not yet been generated.
For each /bill object retrieved, generates an invoice.

Displaying Invoices

To display invoices, use PCM_OP_INV_VIEW_INVOICE.

This opcode uses the POID of the /bill object or /invoice object to locate and retrieve a specific invoice. Specify the output format of the invoice as a mime type in the PIN_FLD_TYPE_STR field in the input flist.If you provide the bill number in PIN_FLD_BILL_NO, the opcode searches the bill database and, if necessary, the history_bills objects.

The PIN_FLD_FLAGS value in the output flist determines the type of invoice to view, for example, a summary or detailed invoice for a nonhierarchical bill unit, and the PIN_FLD_INV_SIZE value in the output flist specifies the size of the invoice returned.

Specify the output format of the invoice as a mime type in the PIN_FLD_TYPE_STR field on the input flist.

PCM_OP_INV_VIEW_INVOICE performs the following tasks:

Uses the PIN_FLD_THRESHOLD_UPPER value in the input flist to determine the maximum size (KB) of the invoice to be viewed. If the invoice is larger than the size specified, an error message and the invoice size, rather than the invoice itself, is displayed.
Checks the following fields in the /invoice object:
- PIN_FLD_INV_SIZE to determine the size of the invoice.
  
  If the invoice size is greater than the invoicing threshold value, PCM_OP_INV_VIEW_INVOICE does not try to format the invoice.
  
  If the invoice size is less than the invoicing threshold, PCM_OP_INV_VIEW_INVOICE continues processing.
  
  To set the maximum size in kilobytes of invoices that can be sent by email, use the inv_send_size parameter in the pin_inv_send utility. This entry is used by PCM_OP_INV_VIEW_INVOICE to restrict sending large invoices to the Email Data Manager (dm_email).
- PIN_FLD_INV_FLAGS to determine the type of invoice to view.
- PIN_FLD_TYPE_STR to determine whether the format specified is stored in the object. Invoices can be stored in the database in pin_flist, XML, HTML, or DOC1 format.
  
  If the specified format is stored, the invoice is retrieved and returned in the format specified. If the specified format is not stored, PCM_OP_INV_POL_FORMAT_VIEW_INVOICE is called to attempt to format the invoice. Invoices can use HTML, XML, or DOC1 format. To apply an XSL style sheet to the invoice, specify the XSL mime type in the PIN_FLD_TYPE_STR field.

If successful, PCM_OP_INV_VIEW_INVOICE returns a buffer containing the formatted invoice. The PIN_FLD_RESULT value in the output flist is 1.

If not successful due to system errors, no invoice is returned. The PIN_FLD_RESULT value is 0.

If not successful because the invoice exceeded the threshold size, the PIN_FLD_RESULT value is 2.

Defining the Invoice Type

The PIN_FLD_INV_TYPE field in the /payinfo object defines which type of invoice to generate for a given bill unit. Table 15-2 lists the possible values for PIN_FLD_INV_TYPE and the corresponding type of invoice that BRM generates.

Table 15-2 PIN_FLD_INV_TYPE Values and Invoice Generated by BRM

Value	Binary Notation	Regular Invoice (if) Generated	Corrective Invoice (if) Generated
0	0000 0000	Detail	Detail Replacement Invoice
1	0000 0001	Summary	Detail Replacement Invoice
2	0000 0010	Detail	Summary Replacement Invoice
3	0000 0011	Summary	Summary Replacement Invoice
4	0000 0100	Detail	Detail Invoice Correction Letter
5	0000 0101	Summary	Detail Invoice Correction Letter
6	0000 0110	Detail	Summary Invoice Correction Letter
7	0000 0111	Summary	Summary Invoice Correction Letter

Note:

For regular invoices, the -detail and -summary parameters of the pin_inv_accts utility override the PIN_FLD_INV_TYPE field values in the /payinfo object.

For corrective invoices, the -corr_type, -detail, and -summary of the pin_inv_accts utility override the PIN_FLD_INV_TYPE field values in the /payinfo object.

To generate summary invoices, change the value of the PIN_FLD_INV_TYPE field in the /payinfo object to the required value listed in Table 15-2.

To set this value when creating a customer account, pass it in the input flist of the PCM_OP_CUST_COMMIT_CUSTOMER opcode.
To set this value when adding or changing a payment method, pass it in the input flist of the PCM_OP_CUST_SET_PAYINFO opcode.

When this value is set, the PCM_OP_INV_MAKE_INVOICE opcode uses it in conjunction with the position of the bill, in relation to other bills, to set the PIN_FLD_INV_FLAGS value in the /invoice object. Possible values are listed in Table 15-3:

Table 15-3 PIN_FLD_INV_FLAGS Values

Type of invoice	PIN_FLD_INV_FLAGS Hex value
Summary invoice for a nonhierarchical account.	0x0006
Detailed invoice for a nonhierarchical account.	0x0005
Summary invoice for a nonpaying bill unit.	0x000A
Detailed invoice for a nonpaying bill unit.	0x0009
Summary invoice for a parent A/R account. (Nonconsolidated: does not include nonpaying bill unit data).	0x0012
Detailed invoice for a parent A/R account. (Nonconsolidated: does not include nonpaying bill unit data).	0x0011
Summary invoice for a parent A/R account. (Consolidated: includes nonpaying bill unit data).	0x0001A
Detailed invoice for a parent A/R account. (Consolidated: includes nonpaying bill unit data).	0x00019

For information on generating invoices, see "Making Invoices".

How Invoices Are Formatted

To format invoices, use PCM_OP_INV_FORMAT_INVOICE. This opcode performs XSL transformation on an invoice.

PCM_OP_INV_FORMAT_INVOICE is called by PCM_OP_INV_POL_FORMAT_INVOICE_XSLT to apply an XSL style sheet to an invoice. It receives as input an XML formatted invoice and an XSL style sheet. It applies the style sheet to the invoice and returns the formatted invoice.

Note:

The XSL transformation is done in the Java Server with the help of XSLT software.

PCM_OP_INV_FORMAT_INVOICE uses the POID of the /bill object or /invoice object to locate and retrieve a specific invoice. Specify the output format of the invoice as a mime type in the PIN_FLD_TYPE_STR field in the input flist.

PCM_OP_INV_FORMAT_INVOICE performs the following tasks:

Checks the /invoice object to see whether the format specified in the PIN_FLD_TYPE_STR field is stored in the object. Invoices can be stored in the database as pin_flist, XML, HTML, or DOC1 format.
If the specified format is stored, the invoice is retrieved and returned in the format specified.
If the specified format is not stored, PCM_OP_INV_POL_FORMAT_VIEW_INVOICE is called to attempt to format the invoice. Invoices can use HTML, XML, or DOC1 format. To apply an XSL style sheet to the invoice, specify the XSL mime type in the PIN_FLD_TYPE_STR field.

If successful, PCM_OP_INV_FORMAT_INVOICE returns a buffer containing the formatted invoice. The PIN_FLD_RESULT field in the output flist is set to 1.

If unsuccessful, no invoice is returned. The PIN_FLD_RESULT field is set to 0.

Use PCM_OP_INV_POL_PREP_INVOICE to customize invoice formatting. This opcode is called by PCM_OP_INV_MAKE_INVOICE.

For corrective invoicing, PIN_FLD_PREV_BILLINFO field contains the details of previous bills. Additionally, the PIN_FLD_CORRECTION_INFO array under PIN_FLD_OTHER_ITEMS contains all the special items that correspond to the corrective bill and its associated events.

The contents of value in the PIN_FLD_INV_TYPE field determines the contents of the invoice. For example, the invoice for a Detail Replacement shows all the items and events while a Detail Correction letter displays only the special items and its associated. However, both Replacement and Correction Letter invoices show the previous amount, adjusted amount and new amounts for events and items.

Customizing the Layout of Bill Items in Invoices

You can customize the layout of bill items on an invoice.

To list bill items in a different order, use the PCM_OP_INV_POL_PREP_INVOICE policy opcode.

When corrective invoicing is enabled, PIN_FLD_PREV_BILLINFO contains the details of the previous bill (if any). Additionally, the PIN_FLD_CORRECTION_INFO array under PIN_FLD_OTHER_ITEMS contains all the items specific to the corrective bill and its corresponding events.

To make other changes to the layout:

If you are using an HTML invoice template, use the PCM_OP_INV_POL_FORMAT_INVOICE_HTML policy opcode.
If you are using an XSLT style sheet for the invoice template, you can perform this level of customization in the style sheet.

Customizing the Format for Printed Invoices

To format invoices for printing, use PCM_OP_INV_POL_FORMAT_INVOICE.

This opcode is called when invoices are generated to specify if the invoices are to be stored in XML or pin_flist format in the /invoice object. The default is XML.

If the storage format is specified as XML or pin_flist, the return flist contains only the specified format type.
If you customize PCM_OP_INV_POL_FORMAT_INVOICE to generate other formats, the return flist contains the format type along with a buffer containing the formatted invoices.

Any customization of invoice content done by PCM_OP_INV_POL_PREP_INVOICE is passed to PCM_OP_INV_POL_FORMAT_INVOICE prior to storage.

You can customize PCM_OP_INV_POL_FORMAT_INVOICE to generate other storage formats. For example, to store invoices in HTML format, you can add code to call PCM_OP_INV_POL_FORMAT_INVOICE_HTML and then add the formatted invoice to the buffer in the output flist.

Customizing the Format for HTML Invoices

To format invoices in HTML, use PCM_OP_INV_POL_FORMAT_INVOICE_HTML.

This opcode is called by PCM_OP_INV_POL_FORMAT_INVOICE when the invoice format requested is HTML.

If your system has the invoicing-by-service feature enabled, PCM_OP_INV_POL_FORMAT_INVOICE_HTML will display the invoice items by service instance. The /config/invoice_events object belonging to the root account is cached.

Customizing the Format for XML Invoices

To format invoices in XML, use PCM_OP_INV_POL_FORMAT_INVOICE_XML.

This opcode is called by PCM_OP_INV_POL_FORMAT_VIEW_INVOICE when the invoice format requested is XML.

Customizing the Invoice Format by Using an XSL Style Sheet

To format invoices using an XSL style sheet, use PCM_OP_INV_POL_FORMAT_INVOICE_XSLT.

To specify the use of XSL style sheets, set the PIN_FLD_FLAGS field in the /config/invoice_templates object to 1.

This opcode is called by PCM_OP_INV_POL_FORMAT_INVOICE when the /config/invoice_templates object specifies an XSL style sheet.

Customizing the Format for DOC1 Invoices

To format invoices for DOC1, use PCM_OP_INV_POL_FORMAT_INVOICE_DOC1.

Note:

For DOC1 format, you must have the DOC1 software.

This opcode also checks the pin.conf file to see whether your system has service-centric invoicing turned on. If invoicing by service is enabled, this opcode reorganizes the flist so that it displays the invoice items by service instance.

If your system has the invoicing-by-service feature enabled, PCM_OP_INV_POL_FORMAT_INVOICE_DOC1 displays the invoice items by service instance.

Displaying an Invoice On Demand

To display an invoice on demand, use PCM_OP_INV_POL_FORMAT_VIEW_INVOICE. This opcode generates an invoice in the specified format.

BRM can store the invoice in the database in either pin_flist or XML format. The default is pin_flist. The storage format is specified by PCM_OP_INV_FORMAT_VIEW_INVOICE.

PCM_OP_INV_POL_FORMAT_VIEW_INVOICE is called when PCM_OP_INV_VIEW_INVOICE requests an invoice in a format that is not stored on the /invoice object. PCM_OP_INV_POL_FORMAT_VIEW_INVOICE attempts to generate the invoice in the requested format. Invoices may be formatted as HTML or DOC1. An XML format is also available, but it displays as HTML format.

PCM_OP_INV_POL_FORMAT_VIEW_INVOICE calls one of the following policy opcodes, depending on the requested format:

PCM_OP_INV_POL_FORMAT_INVOICE_HTML
PCM_OP_INV_POL_FORMAT_INVOICE_DOC1
PCM_OP_INV_POL_FORMAT_INVOICE_XML
PCM_OP_INV_POL_FORMAT_INVOICE_XSLT

PCM_OP_INV_POL_FORMAT_VIEW_INVOICE checks the PIN_FLD_FLAG field in the /config/invoice_templates object to see whether an XSL style sheet should be applied to the invoice. If the flag is set, PCM_OP_INV_POL_FORMAT_INVOICE_XSLT is called to format the invoice.

PCM_OP_INV_POL_FORMAT_VIEW_INVOICE also checks the pin.conf file to see whether your system has service-centric invoicing turned on. If invoicing by service is enabled, PCM_OP_INV_POL_FORMAT_VIEW_INVOICE reorganizes the flist so that it displays the invoice items by service instance.

Note:

Because the flist is reorganized, if you apply an XSL style sheet to the invoice, you may need to change the style sheet to reflect the change in output created by the service instance organization.

Including Custom Data in Invoices

To customize the data displayed in invoices, use the PCM_OP_INV_POL_PREP_INVOICE policy opcode.

This policy opcode searches the database for information about the account and creates an flist of relevant fields to include at invoicing time.

You can customize invoice information by performing additional data searches, or modifying large invoice flists. Customization done by the PCM_OP_INV_POL_PREP_INVOICE policy opcode is passed to the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode, where the storage format is specified.

You can customize the events listed on an invoice as follows:

Include noncurrency events. By default, BRM invoices list all events with a currency balance impact greater than zero. Use the PCM_OP_INV_POL_PREP_INVOICE policy opcode to include noncurrency events. For example, you can list hours of usage if you track hours as part of a promotion.
List fewer or more events. Use the PCM_OP_INV_POL_PREP_INVOICE policy opcode.

Note:

Using the PCM_OP_INV_POL_PREP_INVOICE policy opcode to control which event information is displayed on invoices at invoicing time can affect performance if you access information normally not stored in the PIN_FLD_INVOICE_DATA field of the event. You will get better performance if you define the event information to be stored for invoicing when the event is created by using the PCM_OP_ACT_POL_SPEC_EVENT_CACHE policy opcode.

You must modify this policy opcode to enable messaging through the Universal Messaging Service (UMS).

Changing the Trial Billing Watermark

To distinguish the trial invoice from the regular invoice, a Trial Invoice watermark is added to all the pages after the first page. You can change the watermark text by editing the PIN_FLD_MESSAGE field's value in the PCM_OP_INV_POL_PREP_INVOICE flist.

Including the Time Zone in Invoices

By default, invoices do not show the customer's time zone. To show the time zone on an invoice, do one of the following:

If you are using an HTML invoice template, use the PCM_OP_INV_POL_FORMAT_INVOICE_HTML policy opcode.
If you are using an XSLT invoice template, edit the style sheet to use the PIN_FLD_TIMEZONE_ADJ_END_T and PIN_FLD_RATED_TIMEZONE_ID fields instead of the PIN_FLD_END_T field for the events.

Adding Soft Descriptors to Invoices

Customize PCM_OP_PYMT_POL_PRE_COLLECT to add soft descriptor information to an invoice.

Note:

You can also customize PCM_OP_PYMT_POL_PRE_COLLECT to set a minimum amount to charge.

This example shows how to retrieve the merchant name and a package descriptor. The maximum entry is 22 characters including spaces. If the information is longer than 22 characters, it is truncated on the statement.

pin_flist_t*sub_flistp = NULL;
void*vp = NULL;

/*
 * For each element in the PIN_FLD_CHARGES array add the soft
 * descriptors.
 */

/*
 * Add the merchant info substruct for the soft descriptors.
 */

sub_flistp = PIN_FLIST_SUBSTR_ADD(flistp, PIN_FLD_MERCHANT_INFO, ebufp);

/*
 * Add the merchant "doing business as" to the soft descriptors.
 */

vp = (void *) "Broadband Service";
PIN_FLIST_FLD_SET(sub_flistp, PIN_FLD_MERCHANT, vp, ebufp);

/*
 * Read the charge offer information from the account product array to 
 * pick up the /plan object. 
 * (Exercise left to reader.)
 */

/*
 * Read package description from the /plan object
 */
vp = (void *) NULL;
s_flistp = PIN_FLIST_CREATE(&ebuf);
vp = PIN_FLIST_FLD_GET(prod_flistp, PIN_FLD_PLAN_OBJ, 0, ebufp);
PIN_FLIST_FLD_SET(s_flistp, PIN_FLD_POID, vp, ebufp);
PIN_FLIST_FLD_SET(s_flistp, PIN_FLD_DESCR, NULL, ebufp);

/*
 * Read plan info.
 */
PCM_OP(ctxp, PCM_OP_READ_FLDS, 0, s_flistp, &r_flistp, ebufp);
vp = PIN_FLIST_FLD_GET(r_flistp, PIN_FLD_DESCR, 0, ebufp);

/*
 * Add the product name to the soft descriptors.
 */

PIN_FLIST_FLD_SET(sub_flistp, PIN_FLD_PROD_NAME, vp, ebufp);

/*
 * Add the merchant customer service phone number to the soft
 * descriptors.
 */

vp = (void *) "800-PORTAL1"
PIN_FLIST_FLD_SET(sub_flistp, PIN_FLD_PHONE, vp, ebufp);

Specifying Event Fields to Cache for Invoicing

You can improve performance by limiting the amount of information cached. However, when retrieving information, it is quicker to read from a cached field than from the event table.

The PIN_FLD_INVOICE_DATA field in the /event object contains a cache of all fields that need to be handled in invoicing. Use PCM_OP_ACT_POL_SPEC_EVENT_CACHE to define which balance impact fields to cache for invoicing.

By default, the opcode caches the following PIN_FLD_BAL_IMPACTS array fields shown in Table 15-4 in the base table field PIN_FLD_INVOICE_DATA.

Note:

The PIN_FLD_INVOICE_DATA field is limited to 4000 bytes. If the event cache size of the PIN_FLD_INVOICE_DATA field is greater than 4000 bytes, it is ignored, and the invoice displays a 0 amount. For Oracle databases, you can increase the size of the invoice_data column to work around this limitation.

Table 15-4 Cached PIN_FLD_BAL_IMPACTS Fields

Opcode	Description
PIN_FLD_AMOUNT	The account balance impact. The value can be positive or negative.
PIN_FLD_DISCOUNT	The discount applied to the balance impact.
PIN_FLD_IMPACT_TYPE	Balance impact type - rated by BRM rated-engine (0x1), pre-rated (0x2), taxed (0x4), purchase order (0x8), re-rated(0x20), and reverse_rated(0x40).
PIN_FLD_ITEM_OBJ	Link to the item object affected by this event. Applies only to the balance array element that impacts currency balances. (This may be different from the PIN_FLD_ITEM_OBJ field in the base /event object.)
PIN_FLD_QUANTITY	The quantity applied. The number of units actually applied using this pricing.
PIN_FLD_RATE_TAG	Description of the charge pricing used. Same as PIN_FLD_DESCR in the /rate object.
PIN_FLD_RESOURCE_ID	Numeric value of the balance element that is impacted.
PIN_FLD_TAX_CODE	Tax code for the rate used. When taxes do not apply, this field is set to 0.

If you remove these fields from PCM_OP_ACT_POL_SPEC_EVENT_CACHE and leave the event cache turned on, there are no event details in the invoices.

Note:

If you do not use event caching, return a NULL pointer to the caller of PCM_OP_ACT_POL_SPEC_EVENT_CACHE.

You can customize PCM_OP_ACT_POL_SPEC_EVENT_CACHE to cache additional balance impact array fields.

If you turn off caching in the CM configuration file, these fields are read directly from the event table, which slows performance.

Note:

If you remove the default fields of the PIN_FLD_BAL_IMPACTS array from PCM_OP_ACT_POL_SPEC_EVENT_CACHE and leave the event cache turned on, there are no event details in the invoices.
The event cache must not exceed 4000 bytes. If you have a large number of elements in the PIN_FLD_BAL_IMPACTS array, you must disable the event_cache flag in the CM configuration file.

To enable or disable caching of the PIN_FLD_BAL_IMPACTS array, edit the CM configuration file (BRM_home/sys/cm/pin.conf). The default is caching on. Any number except zero enables caching.

- fm_inv     event_cache     1

Decoding Cached Event Data for Invoicing

PCM_OP_INV_DECODE_INVOICE_DATA parses the event data being retrieved for an invoice. This opcode retrieves the contents of the PIN_FLD_INVOICE_DATA field, parses the data, and returns the decoded data in the output flist.

If you customized PCM_OP_INV_POL_SELECT to search for custom event data, you must call PCM_OP_INV_DECODE_INVOICE_DATA.

The input flist contains the PIN_FLD_INVOICE_DATA field, which is a cached string that needs to be decoded. It is limited to 4000 bytes. If the cache size is greater than 4000 bytes, it is ignored.

The output flist contains the PIN_FLD_EXTENDED_INFO substruct, which contains the fields decoded from the PIN_FLD_INVOICE_DATA field.

How Invoices Are Generated

The pin_inv_accts utility runs as part of your daily billing to create a regular invoice for each account that is billed on that day. Additionally, you run pin_inv_accts to generate corrective invoices for any corrective bills generated that day.

The pin_inv_accts utility runs twice to create these invoices: in the first run, invoices are generated for nonpaying bill units in a hierarchy; in the second run, invoices are generated for paying parent bill units and all nonhierarchical bill units. In both runs, this utility calls PCM_OP_INV_MAKE_INVOICE to create an invoice. This is the first opcode that gets called to create an invoice for a designated /bill object.

PCM_OP_INV_MAKE_INVOICE takes the POID of the bill object and calls PCM_OP_INV_POL_SELECT to determine whether custom processing or default processing is used to retrieve the events and items for billing. If custom processing is used, control is handed to PCM_OP_INV_POL_SELECT, which returns the results after the search operations are complete.

If default processing is used, PCM_OP_INV_MAKE_INVOICE performs the following steps:

Retrieves the invoicing threshold value in the /config/business_params object to determine whether invoices for nonpaying bill units should be generated or consolidated into the parent account invoice. If generated, the parent account's invoice will not contain the nonpaying bill unit's invoice data.
Retrieves all required information from the /bill, /account, /billinfo, and /payinfo objects.
- For regular invoices, it uses the PIN_FLD_INV_TYPE field value from the /payinfo object to determine whether to generate a detailed invoice or a summary invoice. If the value is 1, a summary invoice is created. If the value is 0 or NULL, a detailed invoice is created.
- For corrective invoices, the opcode uses the information in the /payinfo object, the PIN_INV_TYPE_OF_CORRECTIVE_INVOICE and PIN_INV_CORRECTIVE__TYPE_TO_USE constants to determine whether it must generate a summary or detailed version of Replacement Invoice or Invoice Correction Letter.
- For each billable item in an invoice correction letter, PCM_OP_INV_MAKE_INVOICE calls PCM_OP_AR_GET_ALLOCATED_AR_ITEMS which retrieves the allocated special items and additional information to filter out billable items.
- It uses the PIN_FLD_AR_HIERARCHY_SIZE value to determine if multithreaded processing should be used. This value defines the number of nonpaying child bill units allowed for paying parent bill units. If the PIN_FLD_AR_HIERARCHY_SIZE value for a bill exceeds the invoicing threshold, and the bill is for a paying parent bill unit, PCM_OP_INV_MAKE_INVOICE retrieves the nonpaying bill units in that hierarchy by using multiple threads and processes them first.
  
  Note:
  
  The -detail and -summary parameters of pin_inv_accts override the PIN_FLD_INV_TYPE field value in the /payinfo object.
Retrieves details about promotions purchased by the account, depending on the value of the /config/business_params object's PromotionDetailDisplay entry.
Recalculates the event's total amounts (PIN_FLD_TOTAL) including any sponsored charges.
Retrieves the currency information.
If the invoice data comes from a custom application, reads the /config/invoice_data_map object to determine how to parse the invoice data into an flist.
Updates the PIN_FLD_INV_FLAGS value in the /invoice object, which determines the type of invoice to generate.
Creates the formatted invoice and stores it in the database.
Calls PCM_OP_INV_POL_POST_MAKE_INVOICE to handle errors that occurred in custom operations performed by PCM_OP_INV_POL_SELECT.

When the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_INV_MAKE_INVOICE returns the invoice object but does not create the invoice object in the database. When the flag is not set, it returns the POID of the invoice object in the database.

Note:

Bill Now and on-purchase billing do not generate invoices for nonpaying bill units even when the threshold value is exceeded. The consolidated invoice for the parent (paying) bill unit is always generated.

Customizing Invoice Search Operations

You can customize the search templates during the invoicing operation so not all search operations are performed. To omit any of the search operations, or to modify the search for specific events and items, you use PCM_OP_INV_POL_SELECT, which is called by PCM_OP_INV_MAKE_INVOICE when generating invoices.

PCM_OP_INV_POL_SELECT enables you to create custom search templates to select which bill items and events are retrieved for invoices. This improves performance during invoicing because BRM performs only selective searches and does not have to process all accounts and events in the defined invoicing period.

BRM uses the PIN_FLD_BOOLEAN field in the output flist of PCM_OP_INV_MAKE_INVOICE to determine whether the invoices should be generated using the default item and event processing in PCM_OP_INV_MAKE_INVOICE or the custom item and event processing defined in PCM_OP_INV_POL_SELECT.

PIN_BOOLEAN_FALSE indicates PCM_OP_INV_POL_SELECT is ignored and the output flist to PCM_OP_INV_MAKE_INVOICE is the same as the flist PCM_OP_INV_POL_SELECT received as input. This is the default.
PIN_BOOLEAN_TRUE indicates PCM_OP_INV_POL_SELECT performs the processing. The output flist to PCM_OP_INV_MAKE_INVOICE contains the input flist and the results arrays generated by the custom processing. The output flist generally contains an array of items specified for the invoice, an array of events pertaining to each item returned, and an array of information retrieved from the event's invoice data cache.

PCM_OP_INV_MAKE_INVOICE uses the return flist from PCM_OP_INV_POL_SELECT to format the invoice and store it in the database. If PCM_OP_INV_POL_SELECT was not used for processing, it returns the input flist without changes.

If errors occur during the invoicing operations, use PCM_OP_INV_POL_POST_MAKE_INVOICE to handle them. For example, you can customize this opcode to return the event that caused the invoice failure. When PCM_OP_INV_MAKE_INVOICE encounters errors returned by PCM_OP_INV_POL_SELECT, it sends the error buffer as a string to PCM_OP_INV_POL_POST_MAKE_INVOICE.

Creating Custom Search Templates

To create a custom search template for invoicing, use PCM_OP_INV_POL_SELECT. BRM uses the PIN_FLD_BOOLEAN value in the PCM_OP_INV_POL_SELECT output flist to determine whether to use the default search functionality in PCM_OP_INV_MAKE_INVOICE or the customized search functionality in this opcode.

If you customize PCM_OP_INV_POL_SELECT to search for custom event data, you must call PCM_OP_INV_DECODE_INVOICE_DATA. See "Decoding Cached Event Data for Invoicing".

To customize the invoicing search operations, set up your opcode with the following information:

Specify the invoice template to use.

Note:

The invoice templates and style sheets that define the appearance of invoices are defined in the /config/invoice_templates object. You can define a different appearance for invoices. To load custom style sheets, run the pin_load_invoice_template utility.
Copy the input flist to the output flist.
Define the search criteria for the search template. For example, create the conditions under which A/R items and events are retrieved.
Search for the items defined in the search template.
Compile the results flist.
Append the retrieved items to the output flist.
Search for events corresponding to the retrieved items.
Append the retrieved events to the output flist.
Call PCM_OP_INV_DECODE_INVOICE_DATA to decode the PIN_FLD_ INVOICE_DATA value of the /event object.
Send the result back to PCM_OP_INV_MAKE_INVOICE.

Note:

The events that are recorded on an invoice are defined in the /config/invoice_events object. By default, this object includes A/R events, such as payments and refunds, as well as cycle and usage events. You can create a /config/invoice_events object for custom events so that the search operation retrieves them and the specified attributes get displayed on the invoice. To specify the events recorded on an invoice, run the pin_load_invoice_events utility.

Example: Generating Invoices Based on Event Types

You can customize your database so that invoices contain a specific set of data based only on events you want. For example, you can generate invoices for your system that contain only adjustment and dispute information.

To do this:

In PCM_OP_INV_POL_SELECT, create the following search templates. In each template, customize the opcode to retrieve the items and events listed.

Template 1
- /item/adjustment
- /event/billing/adjustment/event
- /event/billing/adjustment/item
- /event/billing/adjustment/tax_event
Template 2
- /item/dispute
- /event/billing/dispute/event
- /event/billing/dispute/item
- /event/billing/dispute/tax_event
Append the search results from Template 1 and Template 2 to the output flist.
Customize the invoicing policy opcodes to display and print the A/R information retrieved by the search templates.

Note:

To generate invoices on a per-bill-unit basis, rather than a system-wide basis, you must extend the /payinfo storable class to define the account-specific attributes. Then customize PCM_OP_INV_POL_SELECT to perform the searches based on the flag values.

Configuring Error Checking for Customized Invoicing

To perform error checking for customized invoicing, use PCM_OP_INV_POL_POST_MAKE_INVOICE. This opcode is called after the invoice commit transaction to troubleshoot the errors detected by PCM_OP_INV_MAKE_INVOICE. If the /invoice object POID value in the PCM_OP_INV_POL_POST_MAKE_INVOICE input flist is type only, the invoice object was not created because errors occurred.

The PIN_FLD_ERROR_INFO array in the input and output flists contain information about the error.

You can configure PCM_OP_INV_POL_POST_MAKE_INVOICE to capture the event that caused the error and return it in the output flist.

Generating Trial Invoices

PCM_OP_BILL_MAKE_TRIAL_BILL calls PCM_OP_INV_MAKE_INVOICE to create the trial invoice. This opcode stores the trial invoice in the primary database schema as an /invoice object (POID type /invoice/trial) and returns an array of trial invoice POIDs for the invoices that were created for the account specified in the input flist. PCM_OP_BILL_MAKE_TRIAL_BILL opens a separate transaction to create the /invoice/trial objects.

If the PIN_FLD_PREINVOICE_MODE field is present in the input flist and has a value of 1, PCM_OP_BILL_MAKE_TRIAL_BILL does not call the invoicing opcode to create trial invoices and only revenue assurance data is generated for the account. If the PIN_FLD_PREINVOICE_MODE field is not present in the input flist or has a value of 0, trial billing creates trial invoices.

Note:

If a start date is not provided in the input flist, PCM_OP_BILL_MAKE_TRIAL_BILL performs trial billing for all billing cycles completed before the end date. For accounts with skipped billing cycles, more than one trial invoice might be created.

How Trial Invoicing Works for Hierarchical Bill Units in BI Publisher 11g

You generate a trial invoice to validate billing charges and check for inaccuracies before creating the final bill.

When you run the pin_trial_bill_accts utility to perform trial billing with BI Publisher, PCM_OP_BILL_MAKE_TRIAL_BILL is called to create the trial invoices and collect revenue assurance data for the trial billing run.

During trial invoicing for hierarchical bill units, PCM_OP_ BILL_MAKE_TRIAL_BILL passes the PIN_FLD_INV_FLAGS field's value to this opcode. This opcode decides from the value whether to create a nonpaying child or parent trial invoice:

If the value is PIN_INV_TYPE_SUBORDINATE, a nonpaying child invoice is created.
If the value is PIN_INV_TYPE_PARENT, a parent invoice is created.

In hierarchical bill unit billing, charges for the nonpaying child bill units are calculated first and then rolled up to the parent bill unit as follows:

When the pin_trial_bill_accts utility is run with the -pay_type parameter and the payment method subordinate ID 10007, PCM_OP_BILL_MAKE_TRIAL_BILL creates a /invoice/trial object for each nonpaying child bill unit.
When the pin_trial_bill_accts utility is run with the -pay_type parameter and the specified payment method parent ID, PCM_OP_BILL_MAKE_TRIAL_BILL is called to trial bill each bill unit. PCM_OP_BILL_MAKE_TRIAL_BILL calculates the parent bill unit bill totals using the nonpaying child totals from PCM_OP_BILL_MAKE_BILL and generates parent invoices.
PCM_OP_BILL_MAKE_TRIAL_BILL passes the PIN_FLD_INV_FLAGS field's value to PCM_OP_INV_MAKE_INVOICE. PCM_OP_INV_MAKE_INVOICE decides from the value whether to create a nonpaying child or paying parent trial invoice:
- If the value is PIN_INV_TYPE_SUBORDINATE, a nonpaying child invoice is created.
- If the value is PIN_INV_TYPE_PARENT, a paying parent invoice is created.
PCM_OP_INV_MAKE_INVOICE calls PCM_OP_INV_POL_PREP_INVOICE, which prepares invoice information prior to formatting and storing.

PCM_OP_INV_POL_PREP_INVOICE checks the value of the PIN_FLD_FLAGS field. If the value is PIN_INV_TYPE_TRIAL_INVOICE plus PIN_INV_TYPE_SUBORDINATE, PCM_OP_INV_POL_PREP_INVOICE adds the PIN_FLD_BILLS array and the PIN_FLD_CHECK_SPLIT_FLAGS field, which are required to generate the trial invoices for the nonpaying child's parent.

The PIN_FLD_BILLS array contains the following fields:
- PIN_FLD_START_T
- PIN_FLD_END_T
- PIN_FLD_AR_BILLINFO_OBJ
- PIN_FLD_DUE
- PIN_FLD_ADJUSTED
- PIN_FLD_WRITEOFF
- PIN_FLD_DISPUTED
- PIN_FLD_RECVD

The PIN_FLD_CHECK_SPLIT_FLAGS is used internally by Oracle Business Intelligence (BI) Publisher to collate nonpaying child invoices into the final invoice.

About Associating Bill Units with a BI Publisher Invoice and Report

When the BRM-BI Publisher integration is enabled, BRM automatically associates bill units with a BI Publisher report name and invoice template name during the account creation process. When an account is created, BRM performs the following for each bill unit in the account:

Determines the BI Publisher invoice report and template that the bill unit qualifies for by reading the /config/business_profile object. This object defines your invoice types, the criteria a bill unit must meet for the invoice type, and the BI Publisher invoice report and template names associated with the invoice type. For example, a /config/business_profile might define the following in Table 15-5 for a regular bill:

Table 15-5 Business Profile Example

Invoice Type	Criteria	BI Publisher invoice Report and Template Names
Monthly billing	The /billinfo object's PIN_FLD_WHEN field is set to 1.	monthly_invoice_report and monthly_invoice
Quarterly billing	The /billinfo object's PIN_FLD_WHEN field is set to 3.	quarter_invoice_report and quarter_invoice

Creates an /associated_bus_profile object for the bill unit. This object stores the template and report names, and type of invoice associated with invoicing for the bill unit, as an element in a template array called PIN_FLD_TEMPLATE_ARRAY.
- PIN_FLD_TEMPLATE_NAME. The Template name configured in the pair key Template_Name of the corresponding invoicing /config/business_profile object.
- PIN_FLD_REPORT_NAME. The Report name configured in the pair key Report_Name of the corresponding invoicing /config/business_profile object.
- PIN_INV_TYPE. The type of invoice stored as PIN_INV_TYPE_REGULAR or PIN_INV_TYPE_CORRECTIVE.
Associates the bill unit with its /associated_bus_profile object by populating the /billinfo object's PIN_FLD_ASSOC_BUS_PROFILE_OBJ_LIST field.

BRM creates an /associated_bus_profile object for each bill unit in an account by calling the PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE opcode. This opcode is called internally by the PCM_OP_CUST_CREATE_BILLINFO opcode during the account creation process.

Whenever invoice business profiles are modified in the /config/business_profile object, use the PCM_OP_CUST_SET_ASSOCIATED_BUS_PROFILE opcode to update all related /associated_bus_profile objects.

About the /associated_bus_profile Object

If you are using BRM-BI Publisher integration framework to generate invoice documents, at the time of customer account creation, the /associated_bus_profile object is created. The /associated_bus_profile object stores the invoicing business profile information for a /billinfo object. The /associated_bus_profile object contains the layout template name in the PIN_FLD_TEMPLATE _NAME field and the report name in the PIN_FLD_REPORT_NAME field.

Creating /associated_bus_profile Objects

If the BRM-BI Publisher invoicing integration is enabled, during customer account creation, internally the PCM_OP_CUST_CREATE_BILLINFO opcode calls the PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE opcode to create one /associated_bus_profile object for each bill unit in the account.