1. Designing and Generating Invoices
  2. Designing Invoices

2 Designing Invoices

In Oracle Communications Billing and Revenue Management (BRM), you design the appearance of an invoice by creating templates.

Topics in this document:

About Designing Invoice Templates

To design the appearance of an invoice, you create a template.

By default, BRM uses a HTML template (BRM_home/sys/data/config/pin_invoice_template.html). You can define your own template in one of these formats:

  • XSLT style sheets: This is the most flexible and powerful option for designing invoices.

  • HTML files: You can create your own HTML template or modify an HTML template that BRM provides.

  • Hyperlinked Invoice Templates: Use hyperlinked invoice templates to display invoices for large bill unit hierarchies with better memory efficiency.

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

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

Designing XSLT Invoice Templates

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

Note:

By default, BRM supports the Xalan XSLT processor. If you want to use a different XSLT processor, you need to write the implementation for that processor and configure it for BRM. For more information on using custom processors, contact Oracle.

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

Use the PCM_OP_INV_POL_FORMAT_INVOICE_XSLT opcode to customize XSLT invoices. See BRM Opcode Guide.

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 display. 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, enter the following command at the command prompt:

start_formatter

Designing HTML Invoice Templates

You design HTML invoice templates by using an HTML editor. 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 these variables, which are 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 BRM Opcode Guide for more information.

Designing 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 defaulted location of BIP_Home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/.

  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@database_alias
Enter password: password

    where:

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

    • database_alias is the BRM database alias.

    • password is the encrypted password for login.

  3. Run the following command: 

    SQL>@invoice_bursting_HIT.plb

    The stored procedure is loaded.

  4. Type exit to exit SQL*Plus.

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.

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

    Note:

    If you do not use BIP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/ as your repository, navigate to your new repository at this time.

  2. Search for the following:

    _datamodel.xdm

    Rename it to the following:

    _datamodel.xdm.ORIG

  3. Search for the following:

    _datamodel_HIT.xdm

    Rename it to the following:

    _datamodel.xdm

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

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

    Rename it to the following:

    BRM_Corporate_Correction_Invoice.rtf.ORIG

  3. Search for the following:

    BRM_Corporate_Invoice.rtf

    Rename it to the following:

    BRM_Corporate_Invoice.rtf.ORIG

  4. Search for the following:

    BRM_Corporate_Replacement_Invoice.rtf

    Rename it to the following:

    BRM_Corporate_Replacement_Invoice.rtf.ORIG

  5. Search for the following:

    BRM_Corporate_Correction_Invoice_HIT.rtf

    Rename it to the following:

    BRM_Corporate_Correction_Invoice.rtf

  6. Search for the following:

    BRM_Corporate_Invoice_HIT.rtf

    Rename it to the following:

    BRM_Corporate_Invoice.rtf

  7. Search for the following:

    BRM_Corporate_Replacement_Invoice_HIT.rtf

    Rename it to the following:

    BRM_Corporate_Replacement_Invoice.rtf

    Note:

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

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

  9. Save and close the file.

  10. Restart the BI Publisher server.

Modifying the Hyperlink Path Prefix

BI Publisher creates hyperlinks within PDF files. The defaulted directory is in the BI Publisher hierarchy, inaccessible to other users wishing to access the hyperlink. To make these hyperlinks accessible, modify the hyperlink path prefix.

To modify the hyperlink path prefix:

  1. Open the repository/Reports/BRM_Invoices/0.0.0.1/BRM_Bursting_Invoice_Report.xdo/xdo.cfg file in a text editor.

  2. In the xdo.cfg file, add your desired hyperlink path prefix. For example: 

    file:/tmp/ftpinvoices/filename.pdf

    where:

    • ftpinvoices is the prefix for the hyperlink path.

    • filename is the name of the PDF file.

  3. Save and close the file.

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

  5. To allow hyperlinked invoice templates to split PDFs and hyperlinks, set thresholds in /config/business_param and do the following:

    • For normal invoicing, run pin_inv_accts with the -hierarchy flag. For example: 

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

    • For trial invoicing, run pin_trial_bill_accts with the -paytype parameter. For example: 

      - 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, you need to load it into the BRM database by using the pin_load_invoice_template utility.

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

  2. To load an XSLT style sheet, enter: 

    pin_load_invoice_template -brand "0.0.0.1/account 1"-type text/html -locale locale_name -template filename -usexsl

    where:

    • 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, this is the command to load 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 "0.0.0.1/account 1"-type HTML -locale locale_name -template filename

    where:

    • 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, this is the command to load 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

Switching between XSLT and HTML Templates

You can switch between using an XSLT template and using an HTML template without loading a new template.

To switch to an XSLT template, enter:

pin_load_invoice_template -brand "0.0.0.1/account 1"-usexsl

To switch to an HTML template, enter: 

pin_load_invoice_template -brand "0.0.0.1/account 1"