1 Designing and Generating Invoices

This chapter describes how to design and generate Oracle Communications Billing and Revenue Management (BRM) invoices and how to send them to customers.

About Invoices

You can use BRM to generate invoices and provide them to customers. An invoice lists the balance information for a customer's bill. When you use Customer Center to display the invoices, the invoices show the total balance in both primary and secondary currencies (if two currencies are configured with appropriate exchange rates), but show only the primary currency for individual events.

When billing runs, a bill is produced for every bill unit in an account and invoices are generated for each bill. There are two invoice types provided: detailed and summary.

  • A detailed invoice lists the bill items for the bill unit and the events that have currency balance impacts greater than zero. The detailed invoice mode is the default.

    Note:

    Generating detailed invoices requires more system processing and may slow performance.

  • A summary invoice lists only the bill items and not the events.

For accounts in a hierarchical group, the billing data for each subordinate bill unit in a child account is rolled up to the invoice for the parent account receivable (A/R) account. This invoice is referred to as a consolidated invoice because it contains the billing data for the subordinate bill units of each child account in addition to the billing data for the A/R account's bill unit. For information about hierarchical account groups, see "Creating and Managing Hierarchical Account Groups" in BRM Managing Accounts Receivable.

Note:

If you use detailed invoices, generating the consolidated invoice can be system intensive, and the consolidated invoice can be extremely large. Therefore, you can set invoicing thresholds to control the size of the consolidated invoice and the subordinate data contained in it. See "About Invoicing for Hierarchical Account Groups".

BRM Invoice Features

BRM invoices present a set of data related to service usage, charges, discounts, promotions, taxes, and surcharges.

The following are important features of BRM invoices:

  • Support customization. You can customize the information included in an invoice in several ways. See "Customizing the Information Included in Invoices".

  • Support brand-specific invoices. See "About Brand-Specific Invoices".

  • Support localized invoices. See "About Localized Invoices".

  • Support multiple invoices for one customer. See "Defining Multiple Invoices for One Customer".

  • Support different ways to send the invoice to customers. See "Sending Invoices to Customers".

  • Include the following details:

    • Charge summary and usage details. The breakdown of usage charges includes the gross usage charges and applicable discounts and taxes. For example, if the net usage charge is $355.08, the invoice document displays the breakdown as: Gross Charge: 348, Discount: (25.20), and Tax: 32.28.

    • Wireless service usage details (if the customer uses wireless service).

    • Past due amount details from the past bill.

    • Usage details of accounts with multiple phone numbers.

    • Hierarchical account details.

    • Promotion names.

    • A/R actions having currency or non-currency impact, such as adjustment, dispute, settlement, and write-off details.

      Note:

      When the corrective invoice feature is enabled, regular invoices do not include special items allocated in corrective bills from the previous cycles.

If you use the BRM-Oracle Business Intelligence Publisher (BI Publisher) integration framework to generate invoice documents, you can add marketing messages, customer information from a customer relationship management (CRM) system, and messages from accounting department to the invoice. See "Designing and Generating Invoices in Oracle Business Intelligence Publisher 10g".

A sample invoice is in "Understanding Invoice Layout".

About the Invoicing Process

BRM performs the following operations to generate invoices:

  1. When you run the daily billing script, BRM finds accounts at the end of their billing cycle. For a description of this script, see "About Billing Your Customers" in BRM Configuring and Running Billing.

  2. BRM creates a bill for each account bill unit when it runs the pin_bill_accts utility as part of the daily billing script. BRM needs a bill before generating an invoice.

  3. BRM generates an invoice for each bill. See "Generating Invoices".

  4. BRM stores all invoices either in the BRM database schema that contains the invoiced accounts or in a separate invoice-only schema that you set up. For more information, see "Storing Invoices in a Separate Database Schema".

    Important:

    Storing invoices in a separate database schema is supported only on Oracle databases.

After an invoice is generated:

For information about generating invoices, see "Generating Invoices".

You can also customize, enrich, and present BRM invoices by using the capabilities of BI Publisher. For information about generating invoice documents by integrating BRM and BI Publisher capabilities, see "Designing and Generating Invoices in Oracle Business Intelligence Publisher 10g".

About Invoicing for Hierarchical Account Groups

When the pin_inv_accts utility processes bills for parent accounts in an account hierarchy, it searches the BRM database for the subordinate bill units and generates their invoices automatically.

You can set threshold values to ensure system performance is not decreased while processing invoices for large hierarchical account groups. The threshold values set the maximum number of child accounts containing subordinate bill units that can be rolled up to the parent A/R account and processed for invoicing.

If the value of the /bill object's PIN_FLD_AR_HIERARCHY_SIZE field is greater than the threshold value, the parent account's invoice includes information from only the parent bill unit.

If the number of subordinate bill units is less than or equal to the threshold, the parent account's invoice includes subordinate bill unit information.

Important:

If bill suppression is enabled on a parent (A/R) account and the subordinate account threshold is exceeded, invoicing fails. This occurs because subordinate bill units, which use the bill number of their parent account, are generated even when billing for the parent account is suppressed. In such cases, they will not contain bill numbers, which invoices require. To exclude invoicing for these bills, run pin_inv_accts with the -skip_blank_billnos parameter. (Subordinate bill units contain bill numbers only when their parent accounts are billed.)

For information on setting the threshold values, see "Setting Defaults for Hierarchical Group Invoices".

About Viewing Invoices for Subordinate Accounts

If you open a subordinate account in Customer Center and run Bill Now for the account, the account's bill and invoice can be viewed only in the parent account's information page.

When pin_inv_accts is run, it generates invoices for subordinate accounts. You can view these invoices in Customer Center and Self-Care Manager when viewing the subordinate account's information.

In Self-Care Manager, invoices can be viewed only for the account that is logged in. To view an invoice for a subordinate account, the subordinate account must be logged in.

About Brand-Specific Invoices

If you support multiple brands, you can use a separate invoice design for each brand. Create a separate template for each brand and then specify the brand when loading each template. See "Designing Invoice Templates" and "Loading Invoice Templates".

If a brand does not have a template associated with it, BRM uses the system template.

You can also define a different list of event types for each brand's invoices with the pin_load_invoice_events utility. See "pin_load_invoice_events".

About Localized Invoices

You can create localized invoices in BRM, as follows:

  • Use UTF8 encoding for hard-coded text strings in XSLT or HTML invoice templates, such as table titles.

  • Specify the BRM locale when loading your invoice template. See "Loading Invoice Templates".

You can also use DOC1 from Group 1 Software, Inc., to create localized invoices. For information, see the DOC1 documentation.

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 1-1 lists the possible values for PIN_FLD_INV_TYPE and the corresponding type of invoice that BRM generates.

Table 1-1 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. See "Specifying the Type of Corrective Invoice".

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 1-1.

  • 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 1-2:

Table 1-2 PIN_FLD_INV_FLAGS Values

Type of Invoice PIN_FLD_INV_FLAGS Hex Value

Summary invoice for a non-hierarchical account.

0x0006

Detailed invoice for a non-hierarchical account.

0x0005

Summary invoice for a subordinate bill unit.

0x000A

Detailed invoice for a subordinate bill unit.

0x0009

Summary invoice for a parent A/R account.

(Nonconsolidated: does not include subordinate bill data).

0x0012

Detailed invoice for a parent A/R account.

(Nonconsolidated: does not include subordinate bill data).

0x0011

Summary invoice for a parent A/R account.

(Consolidated: includes subordinate bill data).

0x0001A

Detailed invoice for a parent A/R account.

(Consolidated: includes subordinate bill data).

0x00019

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

Defining Multiple Invoices for One Customer

You can define multiple invoices for one customer by identifying each invoice with a unique invoice name. This enables you to assign a specific invoice to a specific bill unit in a customer's account.

For example, a customer wants the invoice for one bill sent to a home address and the invoice for another bill sent to a business address. You can set up two invoices: one with an invoice name of "Home" that contains the customer's home address information and one with an invoice name of "Work" that contains the customer's work address information.

Note:

At any time, you can have only one invoice assigned to a customer account. You can select the invoice type from a list of invoices defined for a customer.

To assign an invoice ID to an invoice, do either of the following:

  • Use Customer Center to set the Invoice payment method ID value of an invoice. You access this field from the Payment Options dialog box when setting up a new payment method for an account during account creation or account maintenance. For more information, see the Customer Center Help.

  • Use a custom CRM system to pass the invoice name in the input flist of PCM_OP_CUST_SET_PAYINFO. Use the PIN_FLD_NAME field in the PIN_FLD_PAYINFO array.

Designing Invoice Templates

The invoice's format is based on a template you create and load. BRM uses the template to display invoices in Customer Center and customer self-care Web pages.

You can use one invoice template for all accounts, or, if you support multiple brands, you can use a separate template for each brand.

By default, BRM uses an HTML template (BRM_home/sys/data/config/pin_invoice_template.html where BRM_home is the directory in which BRM is installed). You can define your own template in one of the following formats:

After you create a template, you load it into BRM. See "Loading Invoice Templates".

If you use a third-party invoice application, you do not need to create an invoice template. You export the invoice data to the external tool. See "Exporting Invoices".

Using XSLT Invoice Templates

BRM uses XSLT style sheets and an XSLT processor to generate HTML invoices that can be displayed in Customer Center or a Web browser.

Note:

By default, BRM supports the Xalan XSLT processor. If you want to use a different XSLT processor, see "Using an XSLT Processor Other Than the Xalan XSLT Processor".

BRM provides two sample style sheets, located in BRM_home/sys/data/config/stylesheets:

  • sample1.xsl: This is the default BRM invoice template.

  • sample2.xsl

You can use or edit these style sheets or create your own XSLT style sheet with a third-party XSLT editor.

You can use an XML version of an invoice as the basis for creating the style sheet. To export an invoice to XML, see "Exporting Invoices".

After you create or modify an XSLT style sheet, you load it into the BRM database by using the pin_load_invoice_template utility. See "Loading Invoice Templates".

Turning on XSLT Style Sheet Processing

If you use XSLT style sheet templates, you need to run the BRM invoice formatter to enable invoices to be displayed. The formatter is a Java process that takes XML data and an XSLT style sheet and generates an HTML invoice.

To run the invoice formatter, run the following command:

start_formatter

Using an XSLT Processor Other Than the Xalan XSLT Processor

You can use an XSLT processor other than the Xalan XSLT processor to generate HTML invoices.

To use an XSLT processor other than the Xalan XSLT processor:

  1. Download the XSLT processor you want to use.

  2. Implement the PXSLTEngineIntf.class available in the BRM_home/jars/pxslt.jar in Java using the downloaded XSLT processor.

  3. Package the generated class file into a .jar file.

  4. Copy the .jar file to BRM_home/jars.

  5. Open the BRM_home/sys/formatter/Infranet.properties file in a text editor.

  6. Search for the following entry:

    infranet.pxslt.engine=com.portal.pxslt.PXSLTEngineXalanImpl

  7. Change this entry to:

    infranet.pxslt.engine=path.PXSLTEngineCUSTOMImpl

    where:

    • path is the location of the new transformation engine.

    • PXSLTEngineCUSTOMImpl is the new transformation engine.

  8. Save and close the file.

  9. Start and stop the invoice formatter by running the following commands:

    stop_formatter

    start_formatter

Using HTML Invoice Templates

You design HTML invoice templates by using an HTML editor or other application. You can use the HTML template provided with BRM as a starting point (BRM_home/sys/data/config/pin_invoice_template.html).

An HTML template needs to include the following variables, which you will find in the default template:

  • _INVOICENUM_

  • _CORPIMAG_

  • _CORPADDR_

  • _CUSTADDR_

  • _AMOUNTDUE_

  • _ACCOUNTSUMMARY_

  • _ITEMS_

  • _EVENTS_

When invoices are generated, data replaces the variables. To add variables, modify the PCM_OP_INV_POL_FORMAT_INVOICE_HTML policy opcode. See "Customizing the Format for HTML Invoices".

After you create an HTML template, you load it into the BRM database by using pin_load_invoice_template. See "Loading Invoice Templates".

Using Hyperlinked Invoice Templates

BRM uses hyperlinked invoice templates to display invoices for large bill unit hierarchies with better memory efficiency. With hyperlinked invoice templates, you can easily navigate the invoice using a hyperlinked table of contents.

Note:

Hyperlinked-invoice-template mode uses FTP delivery to create hyperlink text within PDF files for invoices, because hyperlink text must point to local files and not to links within the BI Publisher server.

To configure hyperlinked invoice templates:

  1. Back up the BI Publisher repository, which has a default location of BIP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/

    where BIP_home is the directory in which BI Publisher is installed.

  2. Load the stored procedures. See "Loading Stored Procedures for Hyperlinked Invoice Templates Reports".

  3. Configure the bursting data source and query by setting up the data model configuration for hyperlinked invoice templates. See "Setting Up the Data Model for Hyperlinked Invoice Templates".

  4. Set up the hyperlinked invoice templates. See "Setting Up the Hyperlinked Invoice Templates".

  5. Add the hyperlink path prefix to repository/Reports/BRM_Invoices/0.0.0.1/BRM_Bursting_Invoice_Report.xdo/xdo.cfg. See "Modifying the Hyperlink Path Prefix".

Loading Stored Procedures for Hyperlinked Invoice Templates Reports

To load the stored procedures:

  1. Go to BRM_home/apps/pin_inv_doc_gen directory.

  2. Run the following command, which starts SQL*Plus:

    sqlplus login/password@database_alias

    where

    • login is the login name to use for connecting to the BRM database.

    • password is the encrypted password for login.

    • database_alias is the BRM database alias.

  3. Run the following command:

    SQL>@ invoice_bursting_HIT.plb

    The stored procedure is loaded.

  4. Run the following command, which exits SQL*Plus:

    SQL>exit

Setting Up the Data Model for Hyperlinked Invoice Templates

To set up the hyperlinked invoice template data model:

  1. Go to BIP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/ directory.

    Note:

    If you do not use BIP_Home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/ as your repository, navigate to your new repository.

  2. Search for the following line:

    _datamodel.xdm

  3. Rename it to the following:

    _datamodel.xdm.ORIG

  4. Search for the following line:

    _datamodel_HIT.xdm

  5. Rename it to the following:

    _datamodel.xdm

  6. Open the _datamodel.xdm file and edit the following:

    PARAMETER1 to __FTP_SERVERNAME__

    PARAMETER4 to __FTP_REMOTE_DIRECTORY__

    where:

    • __FTP_SERVERNAME__ is your FTP server name

    • __FTP_REMOTE_DIRECTORY__ is your FTP destination directory

  7. Save and close the file.

Setting Up the Hyperlinked Invoice Templates

To set up the hyperlinked invoice templates:

  1. Go to the BIP_Home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/Reports/BRM_Invoices/schema_number/BRM_Bursting_Invoice_Report.xdo directory.

  2. Search for the following:

    BRM_Corporate_Correction_Invoice.rtf

  3. Rename it to the following:

    BRM_Corporate_Correction_Invoice.rtf.ORIG

  4. Search for the following:

    BRM_Corporate_Invoice.rtf

  5. Rename it to the following:

    BRM_Corporate_Invoice.rtf.ORIG

  6. Search for the following:

    BRM_Corporate_Replacement_Invoice.rtf

  7. Rename it to the following:

    BRM_Corporate_Replacement_Invoice.rtf.ORIG

  8. Search for the following:

    BRM_Corporate_Correction_Invoice_HIT.rtf

  9. Rename it to the following:

    BRM_Corporate_Correction_Invoice.rtf

  10. Search for the following:

    BRM_Corporate_Invoice_HIT.rtf

  11. Rename it to the following:

    BRM_Corporate_Invoice.rtf

  12. Search for the following:

    BRM_Corporate_Replacement_Invoice_HIT.rtf

  13. Rename it to the following:

    BRM_Corporate_Replacement_Invoice.rtf

    Note:

    You can also load HIT.rtf templates within the BI Publisher server.

  14. In the xdo.cfg file, edit the following:

    <property name="fo-external-link-base-url">file:__FTP_REMOTE_DIRECTORY__</property>

    where:

    • __FTP_REMOTE_DIRECTORY__ is your FTP remote destination directory.

  15. Save and close the file.

  16. Restart the BI Publisher server.

Modifying the Hyperlink Path Prefix

The BI Publisher creates hyperlinks within PDF files. The default directory is in the BI Publisher hierarchy, inaccessible to other users wishing to access the hyperlink.

To modify the hyperlink path prefix:

  1. In the xdo.cfg file, add your desired hyperlink path prefix to repository/Reports/BRM_Invoices/0.0.0.1/BRM_Bursting_Invoice_Report.xdo/xdo.cfg.

    For example:

    file:/tmp/ftpinvoices/filename.pdf

    where:

    • ftpinvoices is the hyperlink path prefix

    • filename is the PDF file name

  2. Save and close the file.

Note:

Copy PDF files that are intended for viewing on another machine in the same directory structure as the source. Alternatively, edit the xdo.cfg file so that the final directory path matches the machine intended for viewing.

Note:

For hyperlinked invoice templates to produce the split PDFs and hyperlinks, set thresholds in /config/business_param and run

  • normal invoicing with -hierarchy flag

    - pin_inv_accts -verbose -hierarchy- pin_inv_accts -verbose -pay_type 10001

  • trial invoicing with the -paytype parameter

    - pin_trial_bill_accts -start xxx -end yyy -pay_type 10007

    - pin_trial_bill_accts -start xxx -end yyy -pay_type 10001

Loading Invoice Templates

After creating your template, load it into the BRM database.

To load an invoice template:

  1. Go to a directory that contains a valid configuration file.

    pin_load_invoice_template uses information in the configuration file to connect to the BRM database. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  2. Run the following command, which loads an XSLT style sheet:

    pin_load_invoice_template -brand "brand_POID"-type text/html -locale locale_name -template filename -usexsl

    where:

    • brand_POID is the POID of a brand account or the root account. Use a brand account POID to assign the template to a specific brand. Use the root account POID if your system does not use brands or if you want the template to be available to multiple brands.

    • locale_name is the BRM locale of the template. See "Locale Names" in BRM Developer's Guide.

    • filename is the name and full path of the template file.

    For example, the following command loads the English template sample1.xsl for the root account:

    pin_load_invoice_template -brand "0.0.0.1/account 1" -type text/html -locale en_US -template /opt/portal/sys/data/config/sample1.xsl -usexsl

  3. To load an HTML template, enter:

    pin_load_invoice_template -brand "brand_POID" -type HTML -locale locale_name -template filename

    where:

    • brand_POID is the POID of a brand account or the root account. Use a brand account POID to assign the template to a specific brand. Use the root account POID if your system does not use brands or if you want the template to be available to multiple brands.

    • locale_name is the BRM locale of the template. See "Locale Names" in BRM Developer's Guide.

    • filename is the name and full path of the template file.

    For example, the following command loads the English template pin_invoice_template.html for the root account:

    pin_load_invoice_template -brand "0.0.0.1/account 1" -type HTML -locale en_US -template /opt/portal/sys/data/config/pin_invoice_template.html

Disabling the Default HTML Template

If you load brand-specific templates into the BRM database, disable the system template that BRM uses by default.

To disable the default HTML template:

  1. Open the Connection Manager (CM) configuration file (BRM_home/sys/cm/pin.conf).

  2. Disable the default template that belongs to the root account by entering a crosshatch (#) at the beginning of the following entry:

    - fm_inv_pol html_template $DM{'db_num'} /config/invoice_templates 101

  3. Save and close the file.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

For information about configuration files, see "Using Configuration Files to Connect and Components" in BRM System Administrator's Guide.

Switching between XSLT and HTML Templates

You can switch between using an XSLT template and using an HTML template without loading a new template. You do this for a specific brand or for root.

To switch to an XSLT template, enter:

pin_load_invoice_template -brand "brand_POID" -usexsl

To switch to an HTML template, enter:

pin_load_invoice_template -brand "brand_POID"

where brand_POID is the POID of a brand account or the root account.

How Invoices Are Formatted

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

This opcode is called by the PCM_OP_INV_POL_FORMAT_INVOICE_XSLT policy opcode 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, the PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode 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.

Generating Invoices

Use the pin_inv_accts utility to generate invoices either automatically as part of daily billing or separately.

For information on how to generate invoices during trial billing, see "About Trial Billing" in BRM Configuring and Running Billing.

Generating Invoices Automatically

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. For more information on pin_bill_day, see "About Running the Billing Scripts" in BRM Configuring and Running Billing.

pin_inv_accts runs twice. In the first run, it performs the following tasks to handle hierarchy groups:

  1. Searches for all bills that have reached the end of their billing cycle and for which invoices have not yet been generated.

  2. Checks the subordinate threshold values in the /config/business_params object to determine the maximum number of child accounts having subordinate bill units that are allowed in the hierarchy group. See "About Invoicing for Hierarchical Account Groups".

  3. For each /bill object retrieved, checks the PIN_FLD_AR_HIERARCHY_SIZE value to determine if it exceeds the threshold value.

  4. If the threshold is exceeded, uses multiple threads to retrieve the subordinate bill units and to generate an invoice for each one.

    Important:

    If bill suppression is enabled on a parent (A/R) account and the subordinate account threshold is exceeded, invoicing fails. This occurs because subordinate bill units, which use the bill number of their parent account, are generated even when billing for the parent account is suppressed. In such cases, they will not contain bill numbers, which invoices require. To exclude invoicing for these bills, run pin_inv_accts with the -skip_blank_billnos parameter. (Subordinate bill units contain bill numbers only when their parent accounts are billed.) See "About Invoicing for Hierarchical Account Groups".

    If no errors occurred, pin_inv_accts runs a second time to generate invoices for parent accounts in hierarchy groups and for non-hierarchical accounts:

  5. Searches for all bills that have reached the end of their billing cycle and for which invoices have not yet been generated.

  6. For each /bill object retrieved, generates an invoice.

If you configured BRM to use a separate database schema for invoices, pin_inv_accts uses the Invoice Data Manager, dm_invoice to store invoices in the separate schema. See "Storing Invoices in a Separate Database Schema".

Generating Invoices Manually

To generate invoices manually:

  1. Run the other billing utilities.

    For the names of the other utilities and the order in which to run them, see "Running Billing Utilities Manually" in BRM Configuring and Running Billing.

  2. (Optional) Store invoices in their own database schema by following the procedures in "Storing Invoices in a Separate Database Schema".

  3. Go to a directory with a valid invoicing configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  4. Run pin_inv_accts and specify any necessary parameters. For example, to generate detailed invoices for bills that have the summary flag set, use the -detail parameter.

    Important:

    If bill suppression is enabled on a parent (A/R) account and the subordinate account threshold is exceeded, invoicing fails. This occurs because subordinate bill units, which use the bill number of their parent account, are generated even when billing for the parent account is suppressed. In such cases, they will not contain bill numbers, which invoices require. To exclude invoicing for these bills, run pin_inv_accts with the -skip_blank_billnos parameter. (Subordinate bill units contain bill numbers only when their parent accounts are billed.) See "About Invoicing for Hierarchical Account Groups".

For more information on the syntax and parameters for pin_inv_accts, see "pin_inv_accts".

Generating Detailed Invoices from an External File

To generate detailed invoices from bills contained in an external file, run pin_inv_accts with the -file parameter:

pin_inv_accts -file filename

The file contents must be in pin_flist format. For example:

0 PIN_FLD_RESULTS      ARRAY [0]
1   PIN_FLD_POID        POID [0] 0.0.0.1 /bill 26011 0
0 PIN_FLD_RESULTS      ARRAY [1]
1   PIN_FLD_POID        POID [0] 0.0.0.1 /bill 26091 0

For more information, see "About Formats for Storing Invoices".

This operation overwrites the PIN_FLD_INVOICE_OBJ value in the /bill object.

Note:

When pin_inv_accts processes bills for parent accounts in an account hierarchy, it searches BRM for the subordinate bill units and generates their invoices automatically. In general, the file should not contain the bills for subordinate bill units; however, if they are present, invoices for the subordinate bill units are generated.

Generating Invoices for Non-Invoice Payment Methods

To generate invoices for non-invoice payment methods, run the following command:

pin_inv_accts -pay_type payment_method_ID

where payment_method_ID is the element ID of the payment method.

For a list of payment methods and their element IDs, see "Understanding Payment Methods" in BRM Managing Customers.

For example, to generate invoices for credit cards, run the utility with the following command:

pin_inv_accts -pay_type 10003

Note:

This generates detailed invoices. To generate summary invoices, customize the PCM_OP_INV_POL_SELECT policy opcode to pass the summary value in the PIN_FLD_FLAGS field on its input flist (PIN_FLD_FLAGS = 0x0002). You can also run pin_inv_accts with the -summary parameter to generate summary invoices.

Improving Performance When Generating Invoices

By default, when generating invoices, BRM searches for all items and events in the database, regardless of whether they are included in the invoice. BRM performs the following search operations in steps, which means that it returns search results in blocks instead of returning all search results at one time:

  • Searches for the /bill object to retrieve the account summary information such as the bill number, billing cycle details, payment due date, and amount due.

  • Searches for items and events associated with the /bill object to retrieve billing information such as purchase fees, cycle fees, and usage fees.

  • Searches for all A/R items and events associated with the /billinfo object to retrieve A/R information such as adjustments, disputes, and refunds.

After the search operations are complete, BRM then categorizes the results and displays only the specified events and items on the invoice.

You can improve performance by using the CM configuration file entries inv_item_fetch_size and inv_event_fetch_size to change the number of items and events returned in a block of search results.

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

  2. Change the value of the inv_item_fetch_size entry.

    The default is 10000.

  3. Change the value of the inv_event_fetch_size entry.

    The default is 10000.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

To customize the search operation (for example, to search for specific items or to omit a step), see "Customizing Invoice Search Operations".

Specifying Event Fields to Cache for Invoicing

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

You can improve performance by limiting the amount of information cached. However, if you need the information, caching a field is quicker than having it read from the event table.

By default, the policy opcode caches the following PIN_FLD_BAL_IMPACTS array fields shown in Table 1-3 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, the PCM_OP_INV_POL_PREP_INVOICE policy opcode is used to determine which event information is displayed on invoices. If you customized the PIN_FLD_INVOICE_DATA field to include more event information, you need to include the same information in the BRM_SDK_Home/source/sys/fm_inv_pol/fm_inv_pol_prep_invoice.c source file.

Table 1-3 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 resources. (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 rate.

PIN_FLD_RATE_TAG

Description of the rate used. Same as PIN_FLD_DESCR in the /rate object.

PIN_FLD_RESOURCE_ID

Numeric value of the resource 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 the PCM_OP_ACT_POL_SPEC_EVENT_CACHE policy opcode and leave the event cache turned on, there will be no event details in the invoices.

Note:

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

You can customize the PCM_OP_ACT_POL_SPEC_EVENT_CACHE policy opcode to cache additional balance impact array fields by modifying the BRM_home/source/sys/fm_act_pol/fm_act_pol_spec_event_cache.c file.

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

Important:

  • If you remove the default fields of the PIN_FLD_BAL_IMPACTS array from the PCM_OP_ACT_POL_SPEC_EVENT_CACHE policy opcode and leave the event cache turned on, there will be 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 or include the required elements in the BRM_SDK_Home/source/sys/fm_inv_pol/fm_inv_pol_prep_invoice.c source 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

The PCM_OP_INV_DECODE_INVOICE_DATA opcode 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.

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 event cache size of the PIN_FLD_INVOICE_DATA field is greater than 4000 bytes, the PCM_OP_INV_POL_PREP_INVOICE policy opcode determines which event information is displayed on invoices. If you customized the PIN_FLD_INVOICE_DATA field to include more event information, you need to include the same information in the BRM_SDK_Home/source/sys/fm_inv_pol/fm_inv_pol_prep_invoice.c source file.

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

Note:

If you defined custom event caching for Pipeline Manager in the /config/invoice_data_map file, you must configure PCM_OP_INV_DECODE_INVOICE_DATA to decode the data.

For information on defining fields to cache for invoicing, see "Specifying Event Fields to Cache for Invoicing".

How Invoices Are Generated

pin_inv_accts 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.

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

How PCM_OP_INV_MAKE_INVOICE Works

PCM_OP_INV_MAKE_INVOICE takes the POID of the bill object and calls the PCM_OP_INV_POL_SELECT policy opcode 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 the PCM_OP_INV_POL_SELECT policy opcode, which returns the results after the search operations are complete.

If default processing is used, PCM_OP_INV_MAKE_INVOICE performs the following:

  • Retrieves the invoicing threshold value in the /config/business_params object to determine whether invoices for subordinate bill units should be generated or consolidated into the parent account invoice. If generated, the parent account's invoice will not contain the subordinate bill unit's invoice data. See "About Invoicing for Hierarchical Account Groups".

  • 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. See "About the Invoicing Process".

    • 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, this opcode calls the PCM_OP_AR_GET_ALLOCATED_AR_ITEMS opcode which retrieves the allocated special items and additional information to filter out billable items. For more on PCM_OP_AR_GET_ALLOCATED_AR_ITEMS, see BRM Developer's Reference.

    • It uses the PIN_FLD_AR_HIERARCHY_SIZE value to determine if multithreaded processing should be used. This value defines the number of subordinate bill units for the parent account of the hierarchy group. If the PIN_FLD_AR_HIERARCHY_SIZE value for a bill exceeds the invoicing threshold, and the bill is for a parent A/R account, PCM_OP_INV_MAKE_INVOICE retrieves the subordinate 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 all events belonging to the bill items based on the /config/invoice_events object for a particular brand.

  • Retrieves details about promotions purchased by the account, depending on the value of the /config/business_params object's PromotionDetailDisplay entry. See "Specifying Whether BRM Displays Promotion Details on Invoices".

  • Recalculates the event's total amounts (PIN_FLD_TOTAL) including any sponsored charges.

  • Retrieves the currency information.

  • If the invoice data comes from Pipeline Manager or 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. See "Defining the Invoice Type".

  • Creates the formatted invoice and stores it in the database.

  • Calls the PCM_OP_INV_POL_POST_MAKE_INVOICE policy opcode to handle errors that occurred in custom operations performed by the PCM_OP_INV_POL_SELECT policy opcode.

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.

Important:

Bill Now and on-demand billing will not generate invoices for subordinate bill units even when the threshold value is exceeded. The consolidated invoice for the parent (paying) bill unit always gets 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 the PCM_OP_INV_POL_SELECT policy opcode, which is called by the PCM_OP_INV_MAKE_INVOICE opcode when generating invoices.

The PCM_OP_INV_POL_SELECT policy opcode 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 this policy opcode 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 the PCM_OP_INV_POL_SELECT policy opcode.

  • PIN_BOOLEAN_FALSE indicates the PCM_OP_INV_POL_SELECT policy opcode 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 the PCM_OP_INV_POL_SELECT policy opcode 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 the PCM_OP_INV_POL_SELECT policy opcode to format the invoice and store it in the database. If the PCM_OP_INV_POL_SELECT policy opcode was not used for processing, it returns the input flist without changes.

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

For information on changing the events displayed on an invoice, see "Including Payment, A/R, and Taxation Details in Invoices".

For information on handling errors, see "Configuring Error Checking for Customized Invoicing".

Creating Custom Search Templates

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

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

  1. 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.

  2. Copy the input flist to the output flist.

  3. Define the search criteria for the search template. For example, create the conditions under which A/R items and events are retrieved.

  4. Search for the items defined in the search template.

  5. Compile the results flist.

  6. Append the retrieved items to the output flist.

  7. Search for events corresponding to the retrieved items.

  8. Append the retrieved events to the output flist.

  9. Call the PCM_OP_INV_DECODE_INVOICE_DATA opcode to decode the PIN_FLD_INVOICE_DATA value of the /event object.

  10. 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:

  1. In the PCM_OP_INV_POL_SELECT policy opcode, create the following search templates. In each template, customize the policy 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

  2. Append the search results from Template 1 and Template 2 to the output flist.

  3. 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 need to extend the /payinfo storable class to define the account-specific attributes. Then customize the PCM_OP_INV_POL_SELECT policy opcode to perform the searches based on the flag values.

Configuring Error Checking for Customized Invoicing

To perform error checking for customized invoicing, use the PCM_OP_INV_POL_POST_MAKE_INVOICE policy opcode. This policy 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 input flist of the PCM_OP_INV_POL_POST_MAKE_INVOICE policy opcode 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 the PCM_OP_INV_POL_POST_MAKE_INVOICE policy opcode to capture the event that caused the error and return it in the output flist.

For more information about error handling, see "Understanding API Error Handling and Logging" in BRM Developer's Guide.

Improving Performance by Removing Invoice Details You Do Not Need

By default, BRM invoices include billing details, such as usage items, device details, and tax totals, which helps customers understand the charges on their invoices. If your company does not offer telephony services or if your company does not want to publish certain details on invoices, you can improve invoicing performance by configuring BRM to retrieve only the invoice details needed.

To do so, you use a CM configuration file entry to specify the details to exclude from your invoices:

  • Exclude device details from invoices. Improves performance by configuring BRM to skip the device search and the totaling of resources per device.

    Caution:

    Do not exclude device details if any of the accounts in your system contain devices; otherwise, accounts with devices will have incorrect invoices.

  • Exclude tax totals from invoices. Improves performance by configuring BRM to skip the aggregation of tax totals. Exclude tax totals only if you do not have tax in the entire system and you will not perform A/R actions with taxes.

    Note:

    When you exclude tax totals from invoices, the Taxes and Surcharges line in the invoice Summary of Current Charges section is set to 0.00.

  • Exclude plan, deal, and product pricing details from invoices. Improves performance by configuring BRM to skip the retrieval of plan, deal, and product pricing details from the BRM database. When you exclude plan, deal, and product pricing details, invoices do not include plan names, detail names, or Siebel CRM promotion names.

  • Exclude balance group details. Improves performance by configuring BRM to skip the search for balance group details.

    Note:

    When you exclude balance group details, invoices do not include noncurrency resources.

  • Consolidate the searches for real-time events and batch events into one search. Improves performance by configuring BRM to retrieve BRM and pipeline event details from the BRM cache.

    Note:

    To consolidate the searches, the event_cache entry in the CM configuration file must be enabled. See "Enabling Event Caching".

To improve invoicing performance:

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

  2. Set the inv_perf_features entry to the appropriate value:

    - fm_inv inv_perf_features FlagValue

    where FlagValue is a bitmap flag that specifies the details to exclude from your invoices. Each bit position controls a specific feature. To use multiple features, you must OR the bitmaps. For example, to exclude balance impact details, device details, and tax total details from your invoices, set FlagValue to 0x00003010.

    • 0x00000010 includes balance impact details from invoices.

    • 0x00000800 improves search performance.

    • 0x00001000 excludes device details from invoices.

    • 0x00002000 excludes tax totals from invoices.

    • 0x00004000 excludes plan, deal, product pricing details from invoices.

    • 0x00008000 excludes balance group details from invoices.

  3. Save and close the file.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Customizing the Information Included in Invoices

You can customize the information included in an invoice in several ways:

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.

Creating Service-Centric Invoices

You can create invoices that group items by service. To do this, enable your invoices to show bill items grouped by service. By default, service-centric invoicing is disabled.

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

  2. Do one of the following:

    • To enable service-centric invoicing, set the value of service_centric_invoice to 1:

      - fm_inv_pol service_centric_invoice 1

    • To disable service-centric invoicing, set the value of service_centric_invoice to 0.

  3. Save and close the file.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

For information about configuration files, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

Note:

In the invoicing business profile, if the EnableInvoicingIntegration configuration business parameter is enabled, ensure that in BRM_home/sys/cm/pin.conf, the service_centric_invoice entry is commented out. By default, the service_centric_invoice entry is commented out. If this entry is not commented out, you can view the invoice document only in Customer Center and not in the BI Publisher client.

Including Payment, A/R, and Taxation Details in Invoices

You can specify details about customer's payments, A/R, and taxation details. You can specify a different set of events for each brand. See "pin_load_invoice_events" for details.

For information on customizing the events retrieved during invoicing, see "Customizing Invoice Search Operations".

Including Invoice Event Details

To include details in the invoice:

  1. Open the BRM_home/sys/data/config/events.file file.

  2. Add the event details you want to include in the invoice. See "Events that can be included in the events.file file".

  3. Run the following command, which loads the event file:

    pin_load_invoice_events -brand "brand_poid" -eventfile file

    where brand_poid is the POID of the brand account and file is the name of the events.file file.

    If your system is not brand enabled, brand_poid must be the POID of the root account, 0.0.0.1 /account 1.

  4. To verify that the event types were loaded, you can display the /config/invoice_events object by using Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Events that can be included in the events.file file

To include adjustment details in the invoice, include the following events in the events.file file (if not already present):

  • /event/billing/adjustment/account

  • /event/billing/adjustment/event

  • /event/billing/adjustment/item

  • /event/billing/adjustment/tax_event

To include payment details in the invoice, include the following events in the events.file file (if not already present):

  • /event/billing/payment/cash

  • /event/billing/payment/cc

  • /event/billing/payment/check

  • /event/billing/payment/dd

  • /event/billing/payment/payorder

  • /event/billing/payment/postalorder

  • /event/billing/payment/wtransfer

  • /event/billing/payment/failed

  • /event/billing/payment/voucher

  • /event/billing/payment/voucher_topup

To include payment reversal details in the invoice, include the following events in the events.file file (if not already present):

  • /event/billing/reversal/cash

  • /event/billing/reversal/cc

  • /event/billing/reversal/check

  • /event/billing/reversal/dd

  • /event/billing/reversal/failed

  • /event/billing/reversal/payorder

  • /event/billing/reversal/postalorder

  • /event/billing/reversal/voucher

  • /event/billing/reversal/wtransfer

To include write-off-related events, include the following events in the events.file file (if not already present):

  • /event/billing/writeoff/bill

  • /event/billing/writeoff/billinfo

  • /event/billing/writeoff/item

  • /event/billing/writeoff/tax_bill

  • /event/billing/writeoff/tax_billinfo

  • /event/billing/writeoff/tax_item

To include refund-related events, include the following events in the events.file file (if not already present):

  • /event/billing/refund/cash

  • /event/billing/refund/cc

  • /event/billing/refund/check

  • /event/billing/refund/dd

  • /event/billing/refund/payorder

  • /event/billing/refund/postalorder

  • /event/billing/refund/wtransfer

To include write-off reversal events, include the following events in the events.file file (if not already present):

  • /event/billing/writeoff_reversal

  • /event/billing/writeoff_reversal/tax

To include dispute and settlement details in the invoice, include the following events in the events.file file (if not already present):

  • /event/billing/settlement/event

  • /event/billing/settlement/item

  • /event/billing/settlement/tax_event

  • /event/billing/dispute/event

  • /event/billing/dispute/item

  • /event/billing/dispute/tax_event

The invoice displays tax-related information of the account whose invoice is generated.

To include tax-related information for the summary invoice, include /event/billing/cycle/tax in the events.file file.

To include any custom event, include the custom event in the events.file. For example, you can include /event/billing/cycle/tax/federal event to the events.files.

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.

Including Shadow Event Adjustment Details in Invoices

When recording a shadow event, you can customize your invoice to either show the adjustment details or show only the result of shadow event adjustments in the end balance.

Shadow events are also created by the BRM rerating process. You use the same configuration entry to show shadow event details for both adjustments and rerating. Therefore, to display adjustment details, you must also display rerating details, and vice versa.

In the CM configuration file (BRM_home/sys/cm/pin.conf), the show_rerate_details entry is set to 0 by default. This configuration controls whether to include shadow adjustment details due to rerating in the invoice details. By enabling this entry, rerated events, which have RERATE_OBJ set, are dropped from the invoice details. This means any shadow adjustment, (for example event adjustment before billing) will create shadow event and remain in the invoice details.

By default, the invoice document generated by using the BRM-BI Publisher integration framework displays all the event details including all shadow events to justify the charges being displayed. (These details are displayed on page 4 of the invoice document). If you enable the show_rerate_details entry (by setting it to 1), the rerated events are not listed in the invoice document. Additionally, if all cycle/one-time/usage events were all rerated, the entire page will contain no entries. (Page 4 of the invoice document will be a blank page.)

Oracle recommends keeping the default value of the show_rerate_details entry for the invoice document generated by using the BRM-BI Publisher integration framework.

To set the shadow event invoice details entry:

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

  2. Set the following entry to 1.

    - fm_inv_pol show_rerate_details 0

    The default is 0.

  3. Save and close the file.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Including Soft Descriptors in Invoices

You can add soft descriptors, which contain information to help customers recognize charges, to credit card and checking account statements. Soft descriptors are available for Paymentech direct debit and credit card processing. The following soft descriptors can be added to customer statements:

  • Your DBA (doing business as) name

  • Your product name

  • Your customer service phone number (instead of your headquarters city)

There are two ways to add soft descriptor information:

Customizing the Policy Source File for Soft Descriptors

You can customize the policy source file for the PCM_OP_PYMT_POL_PRE_COLLECT policy opcode to programmatically retrieve the soft descriptor information.

Note:

You can also customize the PCM_OP_PYMT_POL_PRE_COLLECT policy opcode to set a minimum amount to charge. See "Setting the Minimum Amount to Charge" in BRM Configuring and Running Billing.

The following example shows how to retrieve the merchant name and a plan 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 *) "Portal Internet Service";
PIN_FLIST_FLD_SET(sub_flistp, PIN_FLD_MERCHANT, vp, ebufp);

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

/*
 * Read Plan 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);

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, modifying large invoice flists, or adding additional brand-specific content to branded invoices. 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 and messages 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.

  • Include custom message. Set up a custom solution to read messages from an external database and populate BRM database. Use the PCM_OP_INV_POL_PREP_INVOICE policy opcode to include the message in an invoice. For more information about setting up a custom solution please contact Oracle.

  • List fewer or more events. Use the PCM_OP_INV_POL_PREP_INVOICE policy opcode.

    Important:

    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).

Including Late Payment Fees in Invoices

If you are generating the final invoice document by using the BRM-BI Publisher integration framework, you can customize the invoice data generated in XML format to include the late payment fee. See "Designing and Generating Invoices in Oracle Business Intelligence Publisher 10g".

To include late payment fees in the invoice data generated in XML format:

  1. Extend the /item storable class to include /item/late_fee. See "Creating Custom Fields and Storable Classes" in BRM Developer's Guide.

  2. Open the BRM_home/sys/data/pricing/example/config_item_types.xml file and define a type for the item. For example:

    <ItemTypeElement> 
    <ItemTag>LateFee</ItemTag> 
    <ItemDescription>Late_Fee</ItemDescription> 
    <ItemType precreate="false" type="cumulative">
    /item/late_fee</ItemType> 
</ItemTypeElement>

  3. Save the file.

  4. Run the following command, which loads the configuration item types:

    load_config_item_types config_item_types.xml

  5. Open the BRM_home/sys/data/pricing/example/config_item_tags.xml and define a tag for the new service. For example:

    <ItemTagElement> 
    <ItemTag>LateFee</ItemTag> 
    <EventType>/event/billing/late_fee</EventType> 
    <ServiceType>/account</ServiceType> 
</ItemTagElement>

  6. Save the file.

  7. Run the following command, which loads the configuration item tags:

    load_config_item_tags config_item_tags.xml

Including Finance Charges in Invoices

If you are generating the final invoice document by using the BRM-BI Publisher integration framework, you can customize the invoice data generated in XML format to include the finance charges. See "Designing and Generating Invoices in Oracle Business Intelligence Publisher 10g".

To include finance charges in the invoice data generated in XML format:

  1. Extend the /item storable class to include /item/finance_charges. See "Creating Custom Fields and Storable Classes" in BRM Developer's Guide.

  2. Open the BRM_home/sys/data/pricing/example/config_item_types.xml file and define a type for the item. For example:

    <ItemTypeElement> 
    <ItemTag>FinanceCharges</ItemTag> 
    <ItemDescription>Finance_Charges</ItemDescription> 
    <ItemType precreate="false"     type="cumulative">/item/finance_charges</ItemType> 
</ItemTypeElement>

  3. Save the file.

  4. Run the following command, which loads the configuration item types:

    load_config_item_types config_item_types.xml

  5. Open the BRM_home/sys/data/pricing/example/config_item_tags.xml and define a tag for the new service. For example:

    <ItemTagElement> 
    <ItemTag>FinanceCharges</ItemTag> 
    <EventType>/event/billing/finance_charges</EventType> 
    <ServiceType>/account</ServiceType> 
</ItemTagElement>

  6. Save the file.

  7. Run the following command, which loads the configuration item tags:

    load_config_item_tags config_item_tags.xml

Aggregating Taxes on Invoices

You can create invoices that aggregate taxes for each tax supplier and, within each tax supplier, for each tax code. By default, taxes are not aggregated on invoices.

To aggregate taxes on your invoices:

  1. Open the BRM_home/sys/data/config/bus_params_Invoicing.xml file in an XML editor.

  2. Find the following line:

    <ADSTTaxHandle>disabled</ADSTTaxHandle>

  3. Change disabled to enabled.

    Caution:

    BRM uses the XML in this file to overwrite the existing invoicing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM configuration.

  4. Save the file and rename it bus_params_Invoicing.xml.

  5. Run the following command, which loads this change into the /config/business_params object:

    pin_bus_params bus_params_Invoicing.xml

    Run this command from the BRM_home/sys/data/config directory, which includes support files used by the utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

  6. Read the object with the testnap utility or Object Browser to verify that all fields are correct. See "Reading an Object and Fields" in BRM Developer's Guide.

    Note:

    See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.

  7. Stop and restart the CM. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

Specifying Invoice Data from Pipeline Manager and Custom Applications

If you process events that originate in Pipeline Manager or a custom application, you can create a template to specify the event invoice data so that it can be included in your invoices.

BRM provides a default template file (pin_invoice_data_map) located in BRM_home/sys/data/config. This file includes a default INTEGRATE template for Pipeline Manager invoice data. You can modify the INTEGRATE template or add new templates to the file.

To use this feature, you must do the following:

Using Data Map Templates

Templates in the pin_invoice_data_map file define the fields in invoice data records. If you use different invoice record formats, you can create a template for each record format. The data map file can include any number of templates.

When you define templates, you specify the BRM flist fields that map to the invoice record fields. When the invoice data is processed, the fields are passed in an flist to the invoicing opcodes for processing.

The default INTEGRATE template defines Pipeline Manager invoice data. You can modify the INTEGRATE template or create new templates.

To create or modify templates in the pin_invoice_data_map file:

  1. Open the BRM_home/data/config/pin_invoice_data_map file.

  2. Change the INTEGRATE template or add a new template to the end of the file. Use the following syntax:

    ID template_name
field_level   field_name
field_level   field_name
field_level   field_name
...

    where:

    • template_name is the name of the template.

    • field_level is the level of the field in the flist.

    • field_name is the associated BRM field.

    For example:

    ID INTEGRATE
0 PIN_FLD_CALLING_NUMBER
0 PIN_FLD_CALLED_NUMBER
. . . 
0 PIN_FLD_BAL_IMPACTS
1 PIN_FLD_RATE_TAG
1 PIN_FLD_AMOUNT

  3. Save and close the file.

The order of the fields in the template must correspond to the order of the fields in the invoice record. Any custom invoice data records that you process must follow these rules:

  • Fields must be separated by a pound symbol: #

  • Arrays and substructs must be enclosed in angle brackets: < >

  • Each balance impact element must end with a pipe symbol: |

    Note:

    The pipe is optional after the last element.

  • The first field in the record must be the name of the corresponding invoice data template and be preceded by the @ symbol.

    For example: @INTEGRATE

  • The template name in the record must match the template name in the load_pin_invoice_data_map file.

Loading the Invoice Data Map Templates

After defining invoice data map templates, load them into the BRM database.

Caution:

When you run load_pin_invoice_data_map, it overwrites the existing invoice data templates. If you are updating a set of templates, you cannot load new templates only. You must load complete sets of invoice data templates each time you run load_pin_invoice_data_map.

Important:

To connect to the BRM database, load_pin_invoice_data_map needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

If you defined a custom field for invoicing, you must add the full path name of the mapping file to the load_pin_invoice_data_map utility's pin.conf file. For more information, see "Making Custom Fields Available to Your Applications" in BRM Developer's Guide.

To load the data map templates:

  1. Go to the directory that contains the utility's configuration file.

  2. Run the following command, which loads the data map template:

    load_pin_invoice_data_map -d -v pin_invoice_data_map

Enabling Event Caching

Pipeline Manager caches invoice data before sending it to BRM for processing. Therefore, you must enable event caching to include Pipeline Manager invoice data in your invoices.

To enable event caching:

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

  2. Set the event_cache entry to 1:

    - fm_inv event_cache 1

  3. Save and close the file.

Adding Invoice Data to Pipeline Output

To add data from a pipeline to your invoices, configure the OUT_GenericStream module to add the data to the BRM billing record.

To output invoice data, add the following registry parameter to all OUT_GenericStream modules:

AddInvoiceData = TRUE

This parameter is read by the output grammar. When set to TRUE, the output module adds invoice data to each BRM billing record.

For more information about OUT_GenericStream module registry entries, see "OUT_GenericStream" in BRM Configuring Pipeline Rating and Discounting.

About Formats for Storing Invoices

BRM stores each invoice as an object in the database. By default, BRM stores invoices in the same database schema it stores the accounts you are invoicing. But BRM can also store invoices in a separate schema. For information on how to store invoices in a separate schema, see "Storing Invoices in a Separate Database Schema".

You must store invoices in at least one of two formats:

  • pin_flist: The internal BRM data structure. By default, BRM stores invoice data in this format and then reformats it into HTML format to display in the Invoice Viewer.

    This is the most useful format for the following reasons:

    • Customer Center and Self-Care Manager require pin_flist storage format to display HTML invoices.

    • All the available display options work with invoices stored in pin_flist format.

    • You can write a program that saves the pin_flist invoices in any other format. This is useful to provide invoice data to third-party invoice viewers. For information on the pin_flist format, see "Understanding Flists and Storable Classes" in BRM Developer's Guide.

  • XML: You might use this storage format if you are using XML to design and display invoices. You use this format if you are generating the final invoice document by using the BRM-BI Publisher integration package. See "Designing and Generating Invoices in Oracle Business Intelligence Publisher 10g".

    To use XML as an alternative or additional storage format, modify the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode.

    Note:

    You can store invoice data in pin_flist and XML formats at the same time. To store invoice data in multiple formats, modify the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode. If you use XSL style sheet, you can store the invoice data in pin_flist format and use Customer Center to display invoices.

You have the option of also storing invoices in HTML or DOC1 format. These are primarily display formats, and, in most cases, storing invoices in these formats is not useful. But you might need to store invoices in the same format you use to display them.

Storing invoices in HTML or DOC1 format requires extensive programming. Use the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode.

Storing Invoices in a Separate Database Schema

Important:

Storing invoices in a separate database schema is supported only on Oracle databases.

By default, your invoices are stored in the same database schema that contains the invoiced accounts. However, using a separate schema to store invoices provides the following benefits:

  • Speeds up the invoicing process.

  • Potentially stores a large number of invoices.

  • Enables you to view, email, and print invoices without affecting performance of the main schema.

The procedures for storing invoices in a separate schema include the following:

  1. Installing the Invoice Data Manager

  2. Configuring BRM to Use a Separate Invoice Database Schema

  3. Configuring Invoice Applications to Use a Separate Invoice Database Schema

  4. Starting the Invoice Data Manager

Installing the Invoice Data Manager

Important:

The Invoice Data Manager (DM) is supported only on Oracle databases.

The Invoice DM is not installed by default when you install BRM.

To install the Invoice DM:

  1. Make sure you have a separate database schema installed and available to use for storing invoices.

    See "Installing a Multischema System" in BRM Installation Guide and "Adding Database Schemas to a Multischema System" in BRM System Administrator's Guide.

  2. Copy the dm_oracle binary as dm_invoice in BRM_home/bin directory by running the cp command. For example:

    cp BRM_home/bin/dm_oracle BRM_home/bin/dm_invoice

  3. Open the BRM_home/setup/pin_setup.values file in a text editor.

  4. Add "dm_invoice" to the @COMPONENT_LIST line:

    @COMPONENT_LIST = ("dm_oracle", "dm_invoice", "cm");

    Important:

    Make sure "dm_invoice" appears after "dm_oracle".

  5. Modify the entries in the pin_setup.values file shown in Table 1-4:

    Table 1-4 Entries to be Modified in pin_setup File

    Entry Description

    $INVOICE_DB{'user'}

    Must contain the user name to log in to your invoice schema. This user name must be different from the one used for any other schema in the database.

    $INVOICE_DB{'password'}

    Must contain the password to log in to your invoice schema.

    $INVOICE_DB{'alias'}

    Must contain the database alias of the invoice schema.

    $INVOICE_DB{'Host'}

    Must contain the host name of the machine running the invoice schema.

    $INVOICE_DB{'tables_group'}

    Must contain the name of the data tablespace.

    $INVOICE_DB{'indexes_group'}

    Must contain the name of the index tablespace.

    $DM_INVOICE{'port'}

    Must contain the port number of the Invoice DM.

    $DM_INVOICE{'db_num'}

    Must contain the database schema number of the invoice database.

  6. Install the Invoice DM by doing one of the following:

    • To install all BRM components, run this script:

      Note:

      Before running the pin_setup script, make sure that the database flags are set to NO.
      BRM_home/setup/pin_setup

    • To install only the Invoice DM, run this script:

      BRM_home/setup/scripts/pin_cmp_dm_invoice.pl

    For the complete installation procedure, see "Installing BRM" in BRM Installation Guide.

Configuring BRM to Use a Separate Invoice Database Schema

You must configure the CM to use the Invoice DM and separate invoice database schema.

To configure the CM:

  1. On the machine that contains the CM, open the CM configuration file (BRM_home/sys/cm/pin.conf).

  2. In the invoice_db entry, enter the invoice database schema number.

    For example:

    - fm_cust_pol invoice_db 0.0.6.1 /invoice 0

    0.0.6.1 is the BRM default database schema number for the invoice schema.

    The customer Facilities Module (FM) uses this entry to store the invoice database schema numbers for new customers. BRM uses that information to store the invoices each time you generate invoices.

    Note:

    The invoicing utilities do not use this entry.

  3. Make sure you have a dm_pointer entry for the invoice schema referenced in the invoice_db entry. The pin_inv_accts utility uses this entry.

    For more information, see the documentation in the CM configuration file.

  4. Make sure you have a dm_attributes entry for the invoice schema:

    - cm dm_attributes 0.0.6.1 assign_account_obj,searchable

    For more information, see the documentation in the CM configuration file.

  5. Save and close the file.

  6. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Configuring Invoice Applications to Use a Separate Invoice Database Schema

To use a separate database schema for storing invoices:

  1. Open the invoice configuration file (BRM_home/apps/pin_inv/pin.conf) in a text editor.

  2. In the Invoice DB number section for the pin_inv_send and pin_inv_export applications, change the invoice_db parameter value to your invoice database schema number. The following examples use the BRM default invoice database schema number, 0.0.6.1:

    - pin_inv_send invoice_db 0.0.6.1 /invoice 0
- pin_inv_export invoice_db 0.0.6.1 /invoice 0

  3. Save and close the file.

Starting the Invoice Data Manager

To start the Invoice DM, run the pin_ctl start dm_invoice command.

For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Configuring the Invoice pin.conf for Multiple Database Schemas

In a multischema environment, to store invoices in the database schema 0.0.0.2:

  1. Open the invoice configuration file (BRM_home/apps/pin_inv/pin.conf).

  2. Change the login name in the following entry to your login name:

    - nap login_name name

  3. Change the database parameter value to 0.0.0.2 in the following entries:

    - pin_inv_accts database 0.0.0.2 /search 0
- pin_inv_send database 0.0.0.2 /search 0
- pin_inv_export database 0.0.0.2 /search 0

  4. Save and close the file.

For information on running invoice utilities in a multischema environment, see "Setting Up Invoicing on Multiple Database Schemas".

Displaying Invoices

BRM provides the following options for displaying invoices:

  • The Invoice Viewer in Customer Center. See the discussion about reviewing an invoice in the Customer Center Help.

  • Self-Care Manager customer self-care Web pages.

  • Sample XML invoice viewing utility (pin_inv_view.pl).

  • BI Publisher client, if you use the BRM-BI Publisher integration framework to generate invoice documents.

You can also use a third-party viewer to display invoices. For information on how to format and view invoices, refer to the viewer's documentation.

Note:

  • You cannot change invoice information in the Invoice Viewer.

  • A physical invoice is generated to request payment from each account that has a payment method of Invoice. If your BRM system is properly configured, you can see the invoice files that are stored in the BRM database for accounts with other payment methods.

Using Web Pages

If you use Self-Care Manager, your customers can also display their invoices on your customer self-care Web site. See "Setting Up Customer Self Care with Self-Care Manager" in BRM Managing Customers.

Using the XML Sample Invoice Viewing Utility

You can use the pin_inv_view.pl utility to view your invoices in XML by using the BRM sample style sheet or any other style sheet you specify. This utility uses Perl and CGI to display invoices you select in any XML-capable browser.

To use this utility, go to the BRM_home/source/apps/sampleviewer directory. You need to run make to build pin_inv_view.pl.

Customizing the Format for Online Invoices

To display invoices, use the PCM_OP_INV_VIEW_INVOICE opcode.

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.

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.

    • PIN_FLD_INV_FLAGS to determine the type of invoice to view. See "Defining the Invoice Type".

    • 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, the PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode 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.

Customizing the Format for Printed Invoices

To format invoices for printing, use the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode.

This policy 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 this policy opcode 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 the PCM_OP_INV_POL_PREP_INVOICE policy opcode is passed to the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode prior to storage.

You can customize the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode to generate other storage formats. For example, to store invoices in HTML format, you can add code to call the PCM_OP_INV_POL_FORMAT_INVOICE_HTML policy opcode 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 the PCM_OP_INV_POL_FORMAT_INVOICE_HTML policy opcode.

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

If your system has the invoicing-by-service feature enabled, the PCM_OP_INV_POL_FORMAT_INVOICE_HTML policy opcode will display the invoice items by service instance. If your system is brand enabled, this policy opcode caches all /config/invoice_events objects associated with the specific brand. Otherwise, only the /config/invoice_events object belonging to the root account is cached.

Customizing the Format for XML Invoices

To format invoices in XML, use the PCM_OP_INV_POL_FORMAT_INVOICE_XML policy opcode.

This opcode is called by the PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode 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 the PCM_OP_INV_POL_FORMAT_INVOICE_XSLT policy opcode.

You can brand invoices by using brand-specific XSL style sheets.

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 the PCM_OP_INV_POL_FORMAT_INVOICE policy opcode when the /config/invoice_templates object specifies an XSL style sheet.

For more information about loading and editing XSL style sheets, see "Using XSLT Invoice Templates".

Customizing the Format for DOC1 Invoices

To format invoices for DOC1, use the PCM_OP_INV_POL_FORMAT_INVOICE_DOC1 policy opcode.

Important:

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, the PCM_OP_INV_POL_FORMAT_INVOICE_DOC1 policy opcode displays the invoice items by service instance.

Displaying an Invoice on Demand

To display an invoice on demand, use the PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode. This policy 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 the PCM_OP_INV_FORMAT_VIEW_INVOICE opcode.

The PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode is called when PCM_OP_INV_VIEW_INVOICE requests an invoice in a format that is not stored on the /invoice object. This opcode 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.

The PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode 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

The PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy opcode 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, the PCM_OP_INV_POL_FORMAT_INVOICE_XSLT policy opcode is called to format the invoice.

The PCM_OP_INV_POL_FORMAT_VIEW_INVOICE policy 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 policy opcode reorganizes the flist so that it displays the invoice items by service instance. See "Creating Service-Centric Invoices".

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.

Understanding Invoice Layout

The invoice examples used here are based on the invoice template for individual accounts provided in the BRM-BI Publisher integration.

Note:

By default, the invoice document presents charges in primary currency. However, all the relevant charges details are available in secondary currency in the /invoice object. You can customize the RTF files associated with the layout templates to display the charges details in secondary currency.

The layout of a typical invoice generated using the BRM-BI Publisher integration displays details in the following sections:

Standard Details

This section of the invoice includes the following information:

  • Basic bill information, such as invoice date, invoice number, account number, due date, and bill period. The invoice displays this bill-related information on all the pages.

  • Customer information, such as name and billing address. For hierarchy accounts, the invoice displays parent account information in this section.

  • Amount due, which is a sum of past amount due, current charges, payments, and adjustments.

  • Summary of current charges, which is a sum of different types of service usage charges, other charges and credits, and taxes and surcharges. If a customer has used different types of services, such as GSM and ADSL, this section displays the summary of current charges for GSM and ADSL services separately.

  • A URL for online payments and a support phone number to resolve customer queries.

  • Payment slip, which the customer needs to detach from the invoice and returns when making the payment.

    Figure 1-1 shows the standard data in a typical invoice:

Adjustment, Payment, Promotion, and Other Charges and Credits Details

This section of the invoice includes the following details:

  • Adjustment details: This section displays the adjustments that the customer service representative (CSR) performs on the customer account. The invoice displays the type of adjustment, date on which the adjustment was done, amount adjusted, and the reason for adjustment.

  • Payment details: This section displays the payment type, date on which payment is made, payment amount, and the reason for the payment. For example, if the customer has made a cash payment of $15, the Amount column displays (15).

  • Promotion details: This section displays a list of promotions offered by the service provider. It displays promotion-related details, such as promotion name, promotion validity period, and current status of promotion. For more information on promotions, see "Adding Siebel CRM Promotion Names to Invoices".

  • Other charges and credits details: This section displays information related to dispute, refund, settlement, write-off, and write-off reversal.

    Figure 1-2 shows the adjustment, payment, promotion, and other charges and credits details in a typical invoice:

Figure 1-2 Adjustment Details and Other Charges and Credits on Invoice

Description of Figure 1-2 follows
Description of ''Figure 1-2 Adjustment Details and Other Charges and Credits on Invoice''

Charge Details

For consumer accounts, this section of the invoice displays the usage charge details for a particular phone number. If the user has multiple phone numbers, there are different sections for each phone number; each section displays the charge details corresponding to that number. In a hierarchy, for a parent account, the invoice displays the total charges for each subordinate account.

This section of the invoice also displays plan, service, deal, and product details used by the customer.

Note:

If no device (phone number) is associated with a service, the charge details are displayed under Non Device details section.

  • Resource Details: Includes the details of noncurrency resources available for a service type. For example, it can display the number of free seconds available for the GSM telephony service type.

  • Charge Summary: Displays total charges, which is a sum of recurring charges, one-time charge, taxes and surcharges, and total discounts.

  • Usage Summary: Displays the service usage for different services.

    After summary information section, the invoice displays itemized usage details based on service type. For example, for telephony and SMS services used, the invoice displays two sections for telephony and SMS usage. By default, the invoice displays the rounded-off value of event data record (EDR) usage. To display the exact usage duration in the invoice, you can customize the product so that the usage event is populated with the exact net quantity.

    Note:

    The discount and tax break-up details are available in the invoice data generated in XML format. However, the invoice document in PDF does not display these details in the Usage Summary section.

    Figure 1-3 shows the charge details for a particular number in a typical consumer invoice:

Figure 1-3 Charge Details in Invoice

Description of Figure 1-3 follows
Description of ''Figure 1-3 Charge Details in Invoice''

Sending Invoices to Customers

After generating invoices, you email or print them by using a separate application.

You can also make invoices available on your customer self-care Web site for customers to view. See "Setting Up Customer Self Care with Self-Care Manager" in BRM Managing Customers.

Use the pin_inv_send utility to email electronic invoices or to send printed invoices to your customers. This utility determines whether to email or print an invoice by checking an account's delivery method. The delivery method is set by a CSR in the Payment Setup panel of Customer Center. There are two possible delivery methods:

  • Email: pin_inv_send emails the invoice.

  • Postal: pin_inv_send prints the invoice.

By default, this utility sends invoices in HTML format. You can also specify DOC1 format. For more information, see "pin_inv_send".

Setting the Maximum Invoice Size for Email

To set the maximum size of invoices that can be sent by email:

  1. Open the invoice configuration file (BRM_home/apps/pin_inv/pin.conf).

  2. Set the value of the inv_send_size entry in kilobytes and make sure it is not commented.

    This entry is used by PCM_OP_INV_VIEW_INVOICE to restrict sending large invoices to the Email DM (dm_email).

  3. Save and close the file.

Sending Child Account Invoices to the Parent Account's Email Address

By default, invoices for the subordinate bill units in an account hierarchy are consolidated into the invoice for the paying bill unit of the parent account and sent to the parent account's email address. To handle cases where the parent account's invoice is not consolidated and individual invoices exist for each subordinate bill unit, you can configure pin_inv_send to send all subordinate bill unit invoices to the email address of parent account's invoice:

  1. Open the invoice configuration file (BRM_home/apps/pin_inv/pin.conf).

  2. Change the value of the send_sub_inv_2_parent entry to 1 and make sure it is not commented.

  3. Save and close the file.

Configuring the Email Data Manager for Printing

You can use the third-party tool, HTML to PostScript converter (html2ps), to print invoices. Follow these instructions to download the html2ps tool and to configure the Email DM for printing invoices:

  1. Download from the Internet and install the html2ps converter tool.

  2. Open the Email DM configuration file (BRM_home/sys/dm_email/pin.conf).

  3. In the html2ps entry, enter the path to the html2ps tool.

    For example:

    - dm_email html2ps path_to_html2ps_tool

  4. In the printer entry, enter the name of your printer:

    - dm_email printer printer_name

  5. In the tmp_dir entry, enter the name of the directory where BRM saves temporary HTML and PostScript files when the send utility runs. For example:

    - dm_email tmp_dir /tmp

  6. Save and close the file.

  7. Stop and restart the Email DM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Sending Invoices to Accounts That Use the Invoice Payment Method

To email or print invoices for bills that use the Invoice payment method:

  1. If you store invoices in a separate database schema, enter the database schema number in the invoicing configuration file (BRM_home/apps/pin_inv/pin.conf). For example:

    - pin_inv_send invoice_db 0.0.0.2 /invoice 0

    Then follow the procedures in "Storing Invoices in a Separate Database Schema".

  2. Start the Email DM See "Sending Email to Customers Automatically" in BRM Managing Customers.

  3. Go to a directory with a valid invoicing configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  4. Run the following command:

    pin_inv_send

    For a detailed description of this utility's syntax and parameters, see "pin_inv_send".

Sending Invoices to Accounts That Do Not Use the Invoice Payment Method

To email or print invoices for non-invoice bill units, run the pin_inv_send utility with the pay_type parameter:

pin_inv_send -pay_type id

where id is one of the payment methods shown in Table 1-5:

Table 1-5 Payment Method IDs

Payment Method ID

Undefined

0

Prepaid

10000

Invoice

10001

Debit

10002

Credit card

10003

Direct debit

10005

Smart card

10006

Subordinate

In Customer Center this is called nonpaying.

10007

Beta

10008

Internal

10009

Guest

10010

Cash

10011

Check

10012

Wire transfer

10013

Payorder

10014

Postal order

10015

Voucher

10016

SEPA

10018

Exporting Invoices

You can export the invoices in your database to files in any of the following formats: pin_flist, XML, HTML, or DOC1.

In addition, you can export detailed invoices for accounts that are set up to receive summary invoices and you can export invoices for a list of bills in an external file.

Note:

If you use DOC1 invoice software, you can export BRM invoices in DOC1 format, and then open them in the DOC1 program.

To export invoices to files:

  1. Open the invoicing configuration file (BRM_home/apps/pin_inv/pin.conf) and find the pin_inv_export entries.

  2. If you are exporting to a format other than pin_flist, edit the invoice_fmt entry. Enter one of the following that corresponds to the format you want to use for the invoice files:

    • text/pin_flist

    • text/xml

    • text/html

    • text/doc1

    For example, to create HTML invoice files, enter:

    - pin_inv_export  invoice_fmt text/html

    If you do not edit this entry, pin_inv_export creates files in pin_flist format.

  3. In the export_dir entry, enter the directory in which you want to store the files. You can enter a complete path or a path relative to the directory where you run pin_inv_export:

    - pin_inv_export  export_dir ./invoice_dir

  4. Change to a directory with a valid invoicing configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  5. Run the following command:

    pin_inv_export

    Running pin_inv_export with no parameters creates a separate file for each invoice in the database.

    Tip:

    You can specify a date range to export only invoices created on certain dates.

    To generate trial invoices, run the following command:

    pin_inv_export -verbose -trial

    To generate detail invoices, run the following command:

    pin_inv_export -verbose -detail filename

    where filename is the name of the file that specifies the bills for which invoices are to be generated.

    Important:

    When exporting invoices for parent A/R accounts, and the invoices for the subordinate bills were not consolidated into the A/R account's invoice, a separate invoice file for each subordinate bill unit and the A/R bill unit is exported.

    The file-naming convention is accountPOID_billPOID_date.ext.

    If a subordinate invoice or parent invoice fails during generation, subordinate invoices are not exported.

    Note:

    To determine which invoice file is the parent account invoice, customize the appropriate invoice format policy opcode to generate another file containing the parent invoice file name for a given bill.

    For a description of this utility's syntax and parameters, see "pin_inv_export".

Setting Invoicing Defaults

You can specify the following system defaults for 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 default, customize the PCM_OP_CUST_POL_PREP_PAYINFO policy opcode.

Setting the Default Invoice Type

The PIN_FLD_INV_DETAIL field in the /payinfo object contains the invoice value: detailed (0) or summary (1). You can set this value by passing the value in the PIN_FLD_INV_TYPE field in the input flist of:

  • PCM_OP_CUST_COMMIT_CUSTOMER when creating a customer account.

  • PCM_OP_CUST_SET_PAYINFO when changing a customer's payment information.

Setting Defaults for Hierarchical Group Invoices

BRM automatically generates invoices for the parent bill unit and each subordinate bill unit in an account hierarchy. For example, if an account hierarchy contains two subordinate bill units, BRM generates three invoices: one for the parent bill unit and one for each subordinate bill unit.

You can configure whether invoices for parent bill units also include information from subordinate bill units by modifying fields in the invoicing instance of the /config/business_params object. Specifically, you can configure the following:

  • Whether subordinate A/R items are displayed on a parent A/R account's invoice.

  • The maximum number of subordinate bill units that can be included in a parent A/R account's summary invoice.

    When the number of subordinate bill units is less than the maximum, all subordinate bill units are included on the parent's summary invoice. When the number of subordinate bill units exceeds the maximum, none of the subordinate bill units is included on the parent's invoice.

  • The maximum number of subordinate bill units that can be included in a parent A/R account's detailed invoice.

    When the number of subordinate bill units is less than the maximum, the parent's detailed invoice lists the items and events for all subordinate bill units. When the number of subordinate bill units exceeds the maximum, the parent's detailed invoice does not include subordinate bill unit data.

To specify whether subordinate details are displayed on parent invoices:

  1. Run the following command, which creates an editable XML file for the Invoicing parameter class:

    pin_bus_params -r -c "BusParamsInvoicing" bus_params_Invoicing.xml

    This command creates the XML file named bus_params_Invoicing.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

  2. (Optional) Specify whether to display A/R items for each subordinate bill unit on parent invoices:

    Set the SubArItemsIncluded entry to enabled to display subordinate A/R items on parent invoices and to disabled to display only parent A/R items on parent invoices.

    <SubARItemsIncluded>enabled</SubARItemsIncluded>

  3. (Optional) Set the threshold for summary invoices:

    Search the XML file for the following line and change 0 to the number of subordinate bill units allowed in a parent's summary invoice:

    <ThresholdSubordsSummary>0</ThresholdSubordsSummary>

    If the threshold value is exceeded, the parent A/R account summary invoice will not contain the subordinate bill unit data.

    Note:

    A value of 0 means that BRM does not check the size of the account hierarchy and the parent's A/R account summary invoice automatically includes all subordinate bill unit data.

  4. (Optional) Set the threshold for detailed invoices:

    Search the XML file for the following line and change 0 to the number of subordinate bill units allowed in a parent's detailed invoice:

    <ThresholdSubordsDetail>0</ThresholdSubordsDetail>

    If the number of subordinate bill units exceeds the threshold value, the parent's detailed invoice includes only the parent bill unit's details.

    Note:

    A value of 0 means that BRM does not check the size of the account hierarchy and the parent's A/R account summary invoice automatically includes all subordinate bill unit data.

  5. Save the file and rename it to bus_params_Invoicing.xml.

  6. Run the following command, which loads the change into the /config/business_params object:

    pin_bus_params bus_params_Invoicing.xml

    Run this command from the BRM_home/sys/data/config directory, which includes support files used by the utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

  7. Read the object with the testnap utility or the Object Browser to verify that all fields are correct. See "Reading an Object and Fields" in BRM Developer's Guide.

You do not need to restart the CM to enable these entries.

For more information on invoicing thresholds, see "About Invoicing for Hierarchical Account Groups".

Setting the Maximum Size of Invoices Viewable in Customer Center

To limit the size of invoices that can be displayed in Customer Center.

Important:

Do not modify the default Customer Center properties file (CustomerCenter.properties). The parameters and values specified in the Customized.properties file take precedence over values for identical parameters in the default properties file.

  1. Open the CCSDK_home/CustomerCareSDK/CustCntr/custom/Customized.properties file in a text editor.

  2. Add the following entry to the file:

    view_invoice_max_size=kilobytes

    where kilobytes is the maximum invoice size.

    This sets the maximum size of an invoice in kilobytes that can be displayed in Customer Center. This value is passed in the input flist of PCM_OP_INV_VIEW_INVOICE. See "Displaying Invoices".

  3. Save and close the file.

Setting the Maximum Number of Items in the Search Template

In BRM, you can set the maximum number of items to be retrieved at a time in the PCM_OP_SEARCH and PCM_OP_BULK_WRITE_FLDS search templates; for example, 100 items. The opcodes repeats the search until all the events are searched for the specific items.

You can perform this by setting the InOperatorSize parameter in the invoicing instance of the /config/business_params object.

Note:

You can use the InOperatorSize parameter with the PCM_OP_SEARCH and PCM_OP_BULK_WRITE_FLDS opcodes only when these opcodes are called by PCM_OP_BILL_CYCLE_TAX and PCM_OP_SUBSCRIPTION_RERATE_REBILL opcodes respectively.

To set the maximum number of items in the search template:

  1. Run the following command, which creates an editable XML file for the Invoicing parameter class:

    pin_bus_params -r -c "BusParamsInvoicing" bus_params_Invoicing.xml

    This command creates the XML file named bus_params_Invoicing.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

  2. Open the BRM_home/sys/data/config/bus_params_Invoicing.xml file in an XML editor.

  3. Search for the following line:

    <InOperatorSize>500</InOperatorSize>

  4. Change 500 to a required positive number; for example, 100.

    The opcode retrieves only the specified number of items at a time.

    Note:

    To avoid errors that may occur due to huge search template, modify the default value 500 to 100 or less.

  5. Save the file and rename it to bus_params_Invoicing.xml.

  6. Run the following command, which loads the change into the /config/business_params object:

    pin_bus_params bus_params_Invoicing.xml

    Run this command from the BRM_home/sys/data/config directory, which includes support files used by the utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

  7. Read the object with the testnap utility or the Object Browser to verify that all fields are correct. See "Reading an Object and Fields" in BRM Developer's Guide.

  8. Stop and restart the CM. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Adding Siebel CRM Promotion Names to Invoices

Promotions are marketing bundles that contain multiple products and services, often at reduced prices. When customers order promotions, their invoices, by default, display the products and services that come with the promotion, but the invoice does not display the promotion name itself. This could be confusing to customers and make them wonder if they are being billed correctly. If your BRM system uses Siebel CRM and Oracle Application Integration Architecture (Oracle AIA), you can set up your system to display Siebel CRM promotion names on customer invoices.

When your system is configured to display promotion names, customer invoices display all promotions that are active, were inactivated, or were canceled during the billing cycle in which the invoice is generated. For example, if a customer switched from promotion A to promotion B in January, the customer's January invoice would display both promotion A and promotion B.

To manage promotions, your CSRs must be able to perform the following tasks in Siebel CRM:

  • Add a promotion to a customer's account.

  • Modify a customer's existing promotion.

  • Transfer an existing promotion from one account to another.

  • Inactivate a customer's existing promotion.

  • Cancel a customer's existing promotion.

  • Apply promotions to child accounts in an account hierarchy.

    Note:

    Parent accounts can share their promotions with a child account only if the child account owns the products and discounts associated with the parent's promotion.

You implement this functionality by customizing Siebel CRM to send data through Oracle AIA to the PCM_OP_SUBSCRIPTION_SET_BUNDLE opcode.

How BRM Adds Siebel CRM Promotion Names

When a customer orders a promotion, CSRs enter information about the order in Siebel CRM, which passes the information through Oracle AIA to BRM. For each promotion ordered by an account, BRM:

  • Creates a /purchased_bundle object, which stores information about the promotion, such as the promotion's name, validity dates, and status.

  • Associates the promotion with the products and discounts it is bundled with by setting the PIN_FLD_PLAN_OBJ field of the account's /purchased_product and /purchased_discount objects to the /purchased_bundle POID.

When BRM generates invoices, it retrieves all of the account's purchased products and discounts (/purchased_product and /purchased_discount objects) and, if they are associated with a promotion that is active, was inactivated, or was canceled during the current billing cycle, the /purchased_bundle object as well.

Setting Up BRM Invoices to Display Siebel CRM Promotion Names

To include Siebel CRM promotion names on BRM invoices, do the following:

Specifying Whether BRM Displays Promotion Details on Invoices

When BRM generates invoices, it performs, by default, an additional search for any promotion details associated with each account. All promotion details that are found are stored in the account's /invoice object and displayed on the invoice.

You can enable and disable this search for promotion details by modifying a field in the invoicing instance of the /config/business_params object.

  • When the search for promotion details is enabled, BRM searches for and displays on invoices details about the account's current promotions.

  • When the search for promotion details is disabled, promotion details are not displayed on invoices.

To specify whether BRM invoices display Siebel CRM promotion names:

  1. Open the BRM_home/sys/data/config/bus_params_Invoicing.xml file in an XML editor.

  2. Edit the <PromotionDetailDisplay> element in the XML file:

    • Use disabled to disable the search for promotion details.

    • Use enabled to enable the search for promotion details.

    
<PromotionDetailDisplay>enabled</PromotionDetailDisplay>

    Caution:

    BRM uses the XML in this file to overwrite the existing invoicing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM configuration.

  3. Save and close the file.

  4. Run the following command, which loads this change into the /config/business_params object:

    
pin_bus_params bus_params_Invoicing.xml

    Run this command from the BRM_home/sys/data/config directory, which includes support files used by the utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

  5. Read the object with the testnap utility or Object Browser to verify that all fields are correct. See "Reading an Object and Fields" in BRM Developer's Guide.

    Note:

    See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.

  6. Stop and restart the CM. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

Managing Promotions with Siebel CRM

To add, modify, inactivate, or cancel promotions, you must customize Siebel CRM to accept the following information and pass it to the PCM_OP_SUBSCRIPTION_SET_BUNDLE opcode:

  • Promotion name.

  • Promotion description.

  • Products and discounts bundled with the promotion.

  • Promotion creation date.

  • Promotion validity dates.

  • Promotion status: active, inactive, or canceled.

In an Oracle AIA system, you pass this information from Siebel CRM to BRM through J2EE Connector Architecture (JCA) Resource Adapter, which exposes the BRM API through a JCA common client interface (CCI) as an Interaction. Data required for sending data to PCM_OP_SUBSCRIPTION_SET_BUNDLE is detailed in the Subscription Web service. For more information, see "Connecting J2EE-Compliant Applications to BRM" in BRM JCA Resource Adapter.

To implement the ability to display Siebel CRM promotions on invoices, add the following functionality to Siebel CRM by using the PCM_OP_SUBSCRIPTION_SET_BUNDLE opcode:

Adding a promotion to an account

To add a promotion to a customer's account, pass in details about the promotion to PCM_OP_SUBSCRIPTION_SET_BUNDLE. You must also set the following fields in the opcode's input flist:

  • In the PIN_FLD_BUNDLE_INFO array:

    • Set the PIN_FLD_POID field to a type-only POID for /purchased_bundle.

    • Set the PIN_FLD_STATUS field to 1 to set the promotion's status to Active.

      Note:

      If PIN_FLD_STATUS is not passed in, the promotion's status is set to active by default.

  • In the PIN_FLD_OFFERINGS array, specify the products and discounts associated with the promotion. You must create a separate array for each product and discount in the promotion. In the PIN_FLD_OFFERINGS array:

    • Set the PIN_FLD_POID field to the POID of the /purchased_product or /purchased_discount object.

    • Set the PIN_FLD_BUNDLE_OBJ field to NULL.

    • Set the PIN_FLD_BUNDLE_INFO array to the rec_id of the PIN_FLD_BUNDLE_INFO array at the 0th level of the flist. This specifies to associate the newly created /purchased_bundle object with the specified product or discount during account creation.

Modifying an account's promotion

To modify an account's existing promotion, pass in the promotion details that changed to the PCM_OP_SUBSCRIPTION_SET_BUNDLE opcode:

  • To change a promotion's attributes: In the PIN_FLD_BUNDLE_INFO array, set the PIN_FLD_POID field to the existing /purchased_bundle POID and then pass in only the fields that have changed.

  • To transfer a promotion from one account to another: In the PIN_FLD_BUNDLE_INFO array, set the PIN_FLD_POID field to the existing /purchased_bundle POID and set the PIN_FLD_ACCOUNT_OBJ field to the new /account POID.

  • To add products and discounts to a promotion: In the PIN_FLD_OFFERINGS array, set the PIN_FLD_POID field to the complete POID of the product or discount that is being added to the promotion and set the PIN_FLD_BUNDLE_OBJ field to the complete POID of the /purchased_bundle object.

  • To remove an existing product or discount from a promotion: In the PIN_FLD_OFFERINGS array, set the PIN_FLD_POID field to the complete POID of the product or discount that is being removed from the promotion and set the PIN_FLD_BUNDLE_OBJ field to NULL.

When a promotion is modified, the opcode:

  • Changes the specified /purchased_bundle object.

  • Changes the PIN_FLD_PLAN_OBJ field of the /purchased_product or /purchased_discount object, if a product or discount changed.

  • Generates an /event/billing/bundle/modify object for auditing purposes, if a promotion's attributes changed.

Inactivating an account's promotion

When you inactivate an account's promotion, the PCM_OP_SUBSCRIPTION_SET_BUNDLE opcode sets the promotion's status to Inactive. It does not update the associated product or discount object's PIN_FLD_PLAN_OBJ field. Also, unlike the canceled status, a promotion's details can be modified after it has been inactivated.

To inactivate a promotion, pass in details about the promotion to PCM_OP_SUBSCRIPTION_SET_BUNDLE and set the PIN_FLD_STATUS field in the PIN_FLD_BUNDLE_INFO array to 2.

Canceling an account's promotion

You can no longer make changes to an account's promotion after it has been canceled. When you cancel an account's promotion, the PCM_OP_SUBSCRIPTION_SET_BUNDLE opcode:

  • Sets the promotion's validity end date to the current date.

  • Sets the promotion's status to cancelled.

In addition, the opcode can optionally disassociate the products and discounts from the promotion by changing the PIN_FLD_PLAN_OBJ field of the /purchased_product object and the /purchased_discount object to NULL.

To cancel an account's promotion, call PCM_OP_SUBSCRIPTION_SET_BUNDLE and set the PIN_FLD_STATUS field in the PIN_FLD_BUNDLE_INFO array to 3. To configure the opcode to also disassociate the products and discounts from the promotion, do the following:

  • Set the PIN_FLD_FLAGS field to 1. When set, the opcode searches for and disassociates the account's products and discounts from the promotion. This option decreases processing performance.

  • In the PIN_FLD_OFFERINGS array, set the PIN_FLD_POID field to the complete POID of the product or discount that is being canceled and set the PIN_FLD_BUNDLE_OBJ field to NULL. When set, the opcode disassociates the products and discounts you specify from the promotion.

    Important:

    To improve processing performance, pass in all products and discounts that are associated with the promotion you are canceling.

Using Invoice Templates That Display Promotion Names

To display promotion names and details, your invoices must use a template that includes a space holder for promotion details. The default sample1.xsl template is preconfigured to display promotion names and details. You can use this XSL template or create your own template.

To view promotion details on invoices, do one of the following:

Setting Up Invoicing on Multiple Database Schemas

You can run invoicing in a multischema system in either of the following ways:

Running Invoicing on Multiple Database Schemas One at a Time

Running invoicing utilities on multiple database schemas one at a time requires that you edit the invoicing configuration file each time you run the invoicing utilities. Perform the following procedure before you run invoicing:

  1. Open the invoicing configuration file (BRM_home/apps/pin_inv/pin.conf).

  2. Change the value of the login_name entry to a database account in the schema against which you want to run invoicing.

    For example, to run invoicing using the account root.0.0.0.2, change the login_name entry as follows:

    - nap login_name root.0.0.0.2

  3. Save and close the file.

  4. Run the invoicing utilities.

Running Invoicing on Multiple Database Schemas Simultaneously

Running invoicing on multiple database schemas simultaneously requires that you create parallel instances of the invoicing configuration files, each of which is configured for a particular schema. Then, you run all instances of your invoicing utilities.

  1. For each schema you want to run invoicing on, create a subdirectory under BRM_home/apps/pin_inv.

    For example, BRM_home/apps/pin_inv/db1 for schema 1, BRM_home/apps/pin_inv/db2 for schema 2, and so forth.

  2. Copy the BRM_home/apps/pin_inv/pin.conf file into each new subdirectory.

  3. In each invoicing subdirectory, do the following:

    1. Open the pin.conf file.

    2. Change the database number in the login_name entry to a database account that resides in the schema against which you want to run invoicing.

      For example, to run invoicing using the account root.0.0.0.2, change the login_name entry as follows:

      - nap login_name root.0.0.0.2

    3. Save and close the file.

  4. Run the invoicing utilities from the new subdirectories.

Using an /invoice Subclass

If you add a subclass to the /invoice object and want to use the subclass for invoicing, you must specify the subclass type. There are two ways you can do this:

  • Specify the invoice object database number and type in the PIN_FLD_INVOICE_OBJ field in the /payinfo class. Then, using testnap, change the invoice_obj_type in the payinfo_t table to the subclass type.

  • Edit the CM configuration file (BRM_home/sys/cm/pin.conf) by doing the following:

    1. In the Invoice_db entry, add the subclass extension name to /invoice.

      Important:

      This entry is read during account creation time. Changing it has no effect on existing accounts. If you want the /invoice subclass to apply to existing accounts, you must use the previous method instead.

    2. Change the following line:

      -fm_cust_pol invoice_db 0.0.0.1 /invoice 0

      To this:

      -fm_cust_pol invoice_db 0.0.0.1 /invoice/extension_name -1

      Note:

      This entry is not in the CM pin.conf file by default unless you install the Invoice DM (dm_invoice). You can, however, add the entry yourself.