Generating Invoices in Oracle Analytics Publisher

13 Generating Invoices in Oracle Analytics Publisher

Learn how to generate and customize Oracle Communications Billing and Revenue Management (BRM) invoice documents with Oracle Analytics Publisher.

Topics in this document:

Generating Oracle Analytics Publisher Invoice Documents

You use the pin_inv_doc_gen utility to generate invoice documents by integrating the capabilities of BRM and Oracle Analytics Publisher. This utility takes a set of input parameters, generates the invoice document, and stores the instance of the invoice document generated in the Scheduler database. Based on the input parameters you pass to pin_inv_doc_gen, the utility fetches the corresponding invoice POID, Oracle Analytics Publisher report name, and layout template name of an /invoice object.

To configure pin_inv_doc_gen utility with the Infranet.properties file, see "Configuring the Infranet.properties File for pin_inv_doc_gen".

To run the pin_inv_doc_gen utility:

Configure the docgen.sh batch script to run the appropriate pin_inv_doc_gen command. To view the utility's syntax and parameters, see "pin_inv_doc_gen".
Go to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command which runs the docgen.sh batch script:
```
docgen.sh
```

Generating Invoice Documents for a List of Accounts

You can generate Oracle Analytics Publisher invoice documents for a list of accounts by using the pin_inv_doc_gen utility -accts_list InvoiceList.xml parameter. The number of data units (accounts and bill units) in the InvoiceList.xml file should be within the permissible range for the Data Manager (DM) to search the /invoice objects from the BRM database.

You can specify the number of account and bill unit pairs the pin_inv_doc_gen utility should process at one time by using the infranet.dmsearchargs.size parameter in the Infranet.properties file. The maximum value is 14. For example, if the InvoiceList.xml file lists 20 account and bill unit pairs and the infranet.dmsearchargs.size value is set to 6, the pin_inv_doc_gen utility processes six account and bill unit pairs at a time.

In the InvoiceList.xml file, if you specify the account and bill unit pair of a corporate account, the invoice document is generated only for the specified account and bill unit. If the specified corporate account has child accounts that own only nonpaying bill units, the /invoice objects of those child accounts are not selected for generating the invoice document.

To generate invoice documents for a list of accounts and their bill units:

Create an XML file that lists all of the accounts and bill units for which to create Oracle Analytics Publisher invoices. The XML file must be in the following format:

Note:

You can use the BRM_home/apps/pin_inv_doc_gen/InvoiceList.xml file as an example.
```
<InvoiceDocGenConfig>
   <InvoicingList>
      <Account>101304</Account>
      <Billinfo>402678</Billinfo>
   </InvoicingList>
   <InvoicingList>
      <Account>405304</Account>
      <Billinfo>522678</Billinfo>
   </InvoicingList>
<InvoiceDocGenConfig>
```
Save and close the file.
Go to the BRM_home/apps/pin_inv_doc_gen directory.
Open the docgen.sh batch script in a text editor.
Search for the following line:
```
invoicedocgen.pin_inv_doc_gen -status pending
```
Replace with:
```
invoicedocgen.pin_inv_doc_gen -accts_list InvoiceList
```
where InvoiceList specifies the name and location of the file that includes a list of accounts and bill units for which to create invoice documents. This is the file you created in step1.
Save and close the file.
Go to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command which runs the docgen.sh batch script:
```
docgen.sh
```

Generating Invoice Documents Based on the Account Type

To generate invoices based on the account type:

Go to the BRM_home/apps/pin_inv_doc_gen directory.
Open the docgen.sh batch script in a text editor.
Search for the following line:
```
invoicedocgen.pin_inv_doc_gen -status pending
```
Do one of the following:
- To generate invoice document for consumer account types, replace with:
```
invoicedocgen.pin_inv_doc_gen -type consumer
```
- To generate invoice document for corporate account types, replace with:
```
invoicedocgen.pin_inv_doc_gen -type corporate
```
Save and close the file.
In the command prompt, navigate to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command which runs the docgen.sh batch script:
```
docgen.sh
```

Generating Duplicate Invoice Documents

You can generate duplicate Oracle Analytics Publisher invoice documents for invoices that you have already generated by using the pin_inv_doc_gen utility with the -status generated parameter.

To generate duplicate Oracle Analytics Publisher invoice documents:

Go to the BRM_home/apps/pin_inv_doc_gen directory.
Make sure the infranet.dupinvdir.path entry in the utility's Infranet.properties file specifies the directory in which to write the file. See "Configuring the Infranet.properties File for pin_inv_doc_gen".
Open the docgen.sh batch script in a text editor.
Search for the following line:
```
invoicedocgen.pin_inv_doc_gen -status pending
```

Replace with:

invoicedocgen.pin_inv_doc_gen -status generated

Save and close the file.
In the command prompt, navigate to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command to run the docgen.sh batch script:
```
docgen.sh
```
Note:

Oracle recommends DocMerger as the utility to generate a duplicate invoice with a DUPLICATE watermark. However, you can use this utility only for PDF documents. Hence, you can generate an invoice document with a DUPLICATE watermark only if the original invoice document was generated in PDF.

Generating Invoice Documents for Non-Invoice Accounts

Regardless of the payment type or delivery method, any invoice in pending status can be printed. Therefore, you can generate invoice documents for non-invoice accounts such as credit cards. Oracle Analytics Publisher generates PDFs for any invoice with a non-invoice payment type and stores them in the Oracle Analytics Publisher database.

To deliver invoice documents for non-invoice accounts, configure the delivery method of the bursting query by adding a delivery type (such as FTP) to the DEL_CHANNEL parameter and by adding the appropriate values to PARAMETER 1 through PARAMETER 8 as described in the Oracle Fusion Middleware Report Designer's Guide for Oracle Analytics Publisher.

Generating Invoices for Hierarchical Bill Units with Oracle Analytics Publisher

Bill unit hierarchies enable customers to pay other customers' bills. For more information, see discussions about account and bill unit hierarchies in BRM Managing Accounts Receivable and BRM Configuring and Running Billing.

Generating trial and regular invoices with Oracle Analytics Publisher is suited for large bill unit hierarchies for the following reasons:

Each bill unit is processed within its own transaction, which is later used in the processing cycle.
Each bill unit is not loaded into RAM, which reduces RAM utilization.
Collation is run after the generation of each bill unit within the hierarchy. Each bill unit is arranged in a predetermined sequence and by default is rendered in PDF.

Note:

By default, if any bill unit in the hierarchy fails to generate, collation is halted, and an invoice is not produced.

Setting Up Invoicing for Hierarchical Bill Units

To set up invoicing for hierarchical bill units with Oracle Analytics Publisher:

Ensure that all the preliminary configurations required for billing are completed. See BRM Configuring and Running Billing.
Enable the Oracle Analytics Publisher integration. See "Enabling the BRM-Oracle Analytics Publisher Integration".
Set your system to generate invoice documents using Oracle Analytics Publisher. See "Tasks for Setting Up Invoice Generation".
Verify that BRM is set up with the required templates to generate hierarchical invoices. See "Invoice Template for Hierarchical Bill Units".
Associate bill units with an Oracle Analytics Publisher invoice and report.
Load the business profile information into the BRM database. See "Loading Invoicing Business Profiles into the Database".
Configure the pin_inv_doc_gen utility. See "Configuring the pin_inv_doc_gen Utility".
Verify that BRM and Oracle Analytics Publisher are set to generate the final invoice either with or without nonpaying child bill unit details. See "Setting Nonpaying Child Bill Unit Processing".
Verify that the BRM_home/apps/pin_trial_bill/pin.conf file's Threshold entry is commented out. Setting thresholds limits the number of nonpaying child bill units that are invoiced, which leads to errors when the parent account is trial billed.

Invoice Template for Hierarchical Bill Units

Use the BRM_Corporate_Invoice.rtf template for generating hierarchical bill unit invoices. The BRM_Corporate_Invoice.rtf template includes the following layout and formatting:

Depending on how the hierarchical bill unit tax is calculated, the template adds one of the following labels:
- If the tax is calculated at the nonpaying child bill unit level, a Subord Total (Tax Included) label is added on the first page of the invoice.
- If the tax is calculated at the paying parent bill unit level, a Subord Total (Tax Not Included) label is added on the first page of the invoice.
To distinguish the trial invoice from the regular invoice, a Trial Invoice watermark is added to all the pages after the first page. You can change the watermark text by customizing the PCM_OP_INV_POL_PREP_INVOICE policy opcode. See BRM Opcode Guide.

Setting Nonpaying Child Bill Unit Processing

Note:

When generating invoices for hierarchies, BRM and Oracle Analytics Publisher must be set to process the final invoice either with or without nonpaying child bill units:

If you require an invoice that includes nonpaying details, set BRM to process nonpaying child bill units and Oracle Analytics Publisher to generate a single invoice from a group of invoices.
If you require an invoice that does not include nonpaying details, set BRM not to process nonpaying child bill units and Oracle Analytics Publisher to generate individual invoices.

In BRM and Oracle Analytics Publisher, you can choose whether to include the full nonpaying bill unit details in the parent bill unit's invoice.

When you include the full nonpaying bill unit details, a separate invoice is generated for each nonpaying child bill unit and the totals rolled up into the paying parent's invoice. When the final invoice is generated, each nonpaying invoice is collated and merged into the final invoice.
When you do not include the full nonpaying details for hierarchical bill units, only one parent invoice is created, which contains totals from the nonpaying bill units.

To set nonpaying bill unit processing for hierarchies:

In BRM, set the threshold for the maximum number of nonpaying child bill units allowed in the parent invoice with the ThresholdSubordsSummary and ThresholdSubordsDetail business parameters.
- To generate an invoice for each nonpaying child bill unit and include all of them in the final invoice, set the threshold value higher than the number of nonpaying child bill units.
- To generate an invoice without nonpaying child bill unit details, set the threshold value to less than or equal to the number of nonpaying child bill units.
For more information on how to set the ThresholdSubordsSummary and ThresholdSubordsDetail business parameters, see "Invoicing for Hierarchical Bill Units".
Note:
- A value of 0 disables the threshold parameter. BRM does not create separate invoices for nonpaying child bill units.
- If nonpaying details are not captured in the final invoice, they are still available in the /invoice object of the nonpaying child bill unit.
In Oracle Analytics Publisher, set the BRM_Bursting_Invoice_Report to generate individual invoices or a single invoice from a group of invoices as follows:
1. Log in to Oracle Analytics Publisher.
2. From the menu select Catalog, and then select BRM-Invoices.
3. From the BRM-Invoices section, click the data model 0.0.0.1 link.
  
  The 0.0.0.1 page appears.
4. In the Data Model section, expand the Bursting list and select BRM_Bursting_Invoice_Report_Bursting_Query.
5. From the Split By list in the BRM_Bursting_Invoice_Report_Bursting_Query section, select one of the following:
  - To generate a single invoice from a group of invoices, select /ROW_SET/LIST_ROW/ROW/BILL_NO.
  - To generate individual invoices, select /ROW_SET/LIST_ROW/ROW/OBJ_ID0.
6. Save the data model 0.0.0.1.
7. Exit Oracle Analytics Publisher.
By default the BRM report BRM_Bursting_Invoice_Report is set to create the final invoice from a group of invoices for hierarchical accounts. Invoices with the same bill number are generated and then collated and merged into the parent invoice as a single PDF.

Creating Hierarchical Bill Unit Trial Invoices

To create hierarchical bill unit trial invoices with Oracle Analytics Publisher:

Go to the BRM_home/apps/pin_trial_bill directory.
Run the following command, which creates trial invoices for nonpaying child bill units:
```
pin_trial_bill_accts -pay_type 10007
```
Run the following command, which creates trial invoices for the paying parent bill units:
```
pin_trial_bill_accts -pay_type  ID  
```
where ID is the element ID of the payment method for the parent bill unit. For more information, see "Default Payment Methods" in BRM Configuring and Collecting Payments.
Go to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command to run the docgen.sh batch script:
```
docgen.sh
```

Creating Hierarchical Bill Unit Regular Invoices

To create hierarchical bill unit invoices with Oracle Analytics Publisher:

Go to the BRM_home/apps/pin_billd directory.
Run the following command, which runs billing for nonpaying child bill units:
```
pin_bill_accts -pay_type 10007
```
Run the following command, which runs billing for the paying parent bill units:
```
pin_bill_accts -pay_type  ID
```
where ID is the element ID of the payment method for the parent bill unit. For more information, see "Understanding Payment Methods" in BRM Managing Customers.
Go to the BRM_home/apps/pin_inv_accts directory.
Run the following command, which creates regular invoices for nonpaying child bill units:
```
pin_inv_accts -hierarchy
```
Run the following command, which creates regular invoices for the paying parent bill units:
```
pin_inv_accts -pay_type  ID
```
Go to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command to run the docgen.sh batch script:
```
docgen.sh
```

Regenerating Failed Invoices for Hierarchical Bill Units

When an error occurs in trial billing, generation of the bill unit's invoice stops. You must rerun trial billing on the nonpaying child bill units before rerunning trial billing on the paying parent bill units. You must also regenerate trial invoices on the paying parent bill units that did not contain an error.

To regenerate invoices for hierarchical bill units that failed the last trial billing run:

Fix the errors.
Go to the BRM_home/apps/pin_trial_bill directory.
Run the following command, which reruns trial billing on nonpaying child bill units that contained errors in the last billing run:
```
pin_trial_bill_accts -pay_type 10007 -retry
```
Run the following command, which reruns trial billing on the paying parent bill units that contained an error in the last billing run:
```
pin_trial_bill_accts -pay_type ID -retry
```
where ID is the element ID of the payment method for the parent account. For more information, see "Understanding Payment Methods" in BRM Managing Customers.
Run the following command, which generates trial invoicing for the paying parent bill units that did not contain an error in the last billing run:
```
pin_trial_bill_accts -pay_type ID
```
Go to the BRM_home/apps/pin_inv_doc_gen directory.
Enter the following command to run the docgen.sh batch script:
```
docgen.sh
```

Purging Trial Invoices

To purge trial invoices, run the pin_trial_bill_purge utility.

By default, pin_trial_bill_purge purges invoices with the /invoice/trial POID type. If a custom /invoice subclass exists, invoices with /invoice/custom_subclass/trial POID type are purged.

Note:

If the /invoice class is partitioned, running the purge utility (partition_utils -o) on /invoice purges both regular invoices and trial invoices.

For a description of the syntax and parameters of this utility, see "pin_trial_bill_purge" in BRM Configuring and Running Billing.

For more information about partitioning and purging database tables, see the following in BRM System Administrator's Guide:

Deferred Taxation Limitations for Hierarchical Bill Units

BRM offers two options for deferred taxation: taxes can be consolidated into a single item for both the paying parent and nonpaying child bill units, or taxes can be calculated for each individual nonpaying child bill unit, which are listed as separate items on the parent bill:

When taxes are consolidated into a single item for both the paying parent and nonpaying child bill unit, the total tax is calculated at the parent level for the entire hierarchy using an aggregated total due as its basis. In this instance, the cycle_tax_interval entry in BRM_home/sys/cm/pin.conf configuration file is set as follows:
```
-fm_bill cycle_tax_interval billing
```
Note:

This option is not supported when using trial billing or trial invoicing with Oracle Analytics Publisher for hierarchical bill units.
When taxes are calculated for each individual nonpaying child bill unit, the total tax is a summation of taxes that were calculated for each bill unit. In this instance the cycle_tax_interval entry in BRM_home/sys/cm/pin.conf configuration file is set as follows:
```
-fm_bill cycle_tax_interval accounting
```

Note:

This option is supported when you use trial billing or trial invoicing with Oracle Analytics Publisher for hierarchical bill units, with the following limitations:

The total tax value can contain small rounding errors caused by the system calculating taxes on smaller totals of each bill unit rather than the grand total.
The basis for determining the tax rate is with the individual nonpaying child's bill unit rather than the parent. To avoid tax rate discrepancies between trial and production runs, all tax-affecting attributes (for example, address information and tax exemptions) for all bill units within the hierarchy must be synchronized to those of the parent bill unit.

Troubleshooting Issues with Hierarchical Bill Unit Invoice Generation

This section lists problems you might encounter while trying to generate hierarchical bill unit invoices and provides information on how to fix them.

Nonpaying child invoices not generated

Scenario: A parent account has a paying parent bill unit. Each of the parent account's two child accounts has a nonpaying child bill unit whose paying parent bill unit is owned by the parent account. The ThresholdSubordsSummary and ThresholdSubordsDetail business parameters are set to 1. The following command is run:

pin_inv_accts -pay_type 10018 -verbose

Solution: To create nonpaying child invoices, the pin_inv_accts utility requires the -hierarchy parameter. Run the following commands:

pin_inv_accts –hierarchy -verbose
pin_inv_accts –pay_type 10018 -verbose

Invoice generation is successful, but the billing amounts for the parent bill unit in the final invoice are incorrect

Scenario: One parent account has a paying parent bill unit. Each of the parent account's two child accounts has a nonpaying child bill unit whose paying parent bill unit is owned by the parent account. The ThresholdSubordsSummary and ThresholdSubordsDetail business parameters are set to 1. The following commands are run:

pin_inv_accts -pay_type 10007 -verbose
pin_inv_accts -pay_type 10018 -verbose

Solution: The Oracle Analytics Publisher template is configured with a bursting option, which is using the same invoice details twice. Change the template to a nonbursting option.

See "Setting Nonpaying Child Bill Unit Processing".

Multiple /invoice objects are created instead of one, and after running the docgen.sh script, the invoice is generated, but the amounts are incorrect

pin_inv_accts -pay_type 10007 -verbose
pin_inv_accts -pay_type 10018 -verbose

Solution: Oracle Analytics Publisher is set to create invoices for nonpaying child bill units. Whereas the threshold business parameters setting in BRM is set not to create invoices for nonpaying child bill units. Oracle Analytics Publisher and BRM are in conflict. To solve the conflict, change the template to a nonbursting option.

See "Setting Nonpaying Child Bill Unit Processing".

Error when running multiple trial invoicing runs for standalone accounts

Scenario: Unable to run multiple instances of trial billing on a standalone account. Invoices are not created for the second run. The following commands are run:

pin_trial_bill_accts -pay_type 10001 -verbose
pin_trial_bill_accts -pay_type 10001 -verbose

Solution: As the trial bill number is the same for both trial invoices, Oracle Analytics Publisher is attempting to collate each generated invoice for the final invoice. Include the docgen.sh script after each run to create a final invoice for each instance as follows:

pin_trial_bill_accts -pay_type 10001 -verbose
doc_gen.sh
pin_trial_bill_accts -pay_type 10001 -verbose
doc_gen.sh

Note:

The trial bill number is used to collate invoices in Oracle Analytics Publisher.

Storing the Invoice Document

You can store invoice documents in the Oracle Analytics Publisher Scheduler database. Oracle recommends configuring a separate database, other than the BRM database, to store invoice documents. See "Setting Scheduler Configuration".

Sending Invoice Documents to Your Customers

After generating invoice documents, you can email them to your customers. To send the invoice document through email, you must:

Configure the Scheduler database in Oracle Analytics Publisher. See "Setting Scheduler Configuration".
Configure the email server and FTP in Oracle Analytics Publisher. See "Configuring the Email Server".
Configure the delivery option that is retrieved from the /payinfo object. For more information, see BRM Managing Customers.

Customizing Invoices

Note:

To customize the invoice layout, you should have template-designing experience. See the Oracle Analytics Publisher documentation for instructions on how to create and design layout templates.

You can use the following capabilities of Oracle Analytics Publisher to customize invoice documents:

Customizing invoice format: You can format the sample invoice layout templates or create new invoice templates. See "Customizing Invoice Layout Templates".
Enriching invoice data: You can enrich the data that is displayed in the invoice by getting data from various sources. See "Enriching Invoice Data".

Customizing Invoice Layout Templates

You can customize the invoice layout template by:

Updating the existing layout template file by using Oracle Analytics Publisher Desktop (Template Builder) and Microsoft Word. For more information about updating the layout template in RTF, see the discussion about creating an RTF template in the Oracle Analytics Publisher documentation.
Adding a new layout template file. To do so:
1. Create a new layout template in Oracle Analytics Publisher.
2. Create a new invoicing /config/business_profile object in BRM to reflect the addition of the new layout template. See "Creating an Invoicing Configuration Business Profile".

Enriching Invoice Data

After receiving invoice data from the BRM database, you might want to enrich the invoice data with marketing messages, customer information available in a customer relationship management (CRM) application, and special messages from the accounting department. Oracle Analytics Publisher provides this functionality by retrieving data from additional data sources.

Note:

The sample layout templates that are available with BRM-Oracle Analytics Publisher invoicing integration package display data fetched from only the BRM database. If you want to enrich your invoice document with additional data sources, you need to customize the sample layout templates. See "Customizing Invoice Layout Templates".

To enrich BRM invoice data:

The /invoice objects containing data in XML format should be present in the BRM database.
The additional data source must be configured in Oracle Analytics Publisher to enrich the invoice data. See the discussion of setting up data sources in the Oracle Analytics Publisher documentation.
Configure data and bursting queries to fetch data from custom data source.

For detailed instructions on creating or updating Oracle Analytics Publisher reports based on multiple data sources, see the discussion of creating reports based on various data sources in the Oracle Analytics Publisher documentation.