1. Designing and Generating Invoices
  2. Setting Up Your System to Generate Invoice Documents

12 Setting Up Your System to Generate Invoice Documents

Learn how to configure your Oracle Communications Billing and Revenue Management (BRM) system to generate invoices through Oracle Analytics Publisher.

Topics in this document:

Tasks for Setting Up Invoice Generation

To set up your BRM system for generating invoices using Oracle Analytics Publisher:

  1. Install Oracle Analytics Publisher. To install Oracle Analytics Publisher, follow the instructions in the Oracle Analytics Publisher documentation.

  2. In BRM, specify the Oracle Analytics Publisher invoice report and layout templates names. See "Creating an Invoicing Configuration Business Profile".

  3. In BRM, specify the events that you want included in your invoices by editing the events.file file and then loading it into the BRM database with the pin_load_invoice_events utility. See "Including Payment, A/R, and Tax Details in Invoices".

  4. Install the BRM-Oracle Analytics Publisher invoicing integration package on the Oracle Analytics Publisher server. See "Installing the BRM-Oracle Analytics Publisher Invoicing Integration Package".

  5. Configure the pin_inv_doc_gen utility. See "Configuring the pin_inv_doc_gen Utility".

  6. Configure the data source and data model.

  7. Configure for multischema. Store and modify copies of the report in each schema.

Creating an Invoicing Configuration Business Profile

When the BRM-Oracle Analytics Publisher integration is enabled, BRM automatically performs the following during the bill unit creation process:

  • Reads the invoicing configuration business profile (/config/business_profile object) to determine which invoice report and layout template the bill unit should be associated with.

  • Creates an /associated_bus_profile object for the bill unit. This object specifies the names of the Oracle Analytics Publisher invoice report and layout template to use.

  • Links the bill unit to the /associated_bus_profile object it created.

To create an invoicing configuration business profile:

  1. Enable the BRM-Oracle Analytics Publisher integration. See "Enabling the BRM-Oracle Analytics Publisher Integration".

  2. Specify the requirements for a bill unit to be associated with an invoicing configuration business profile by creating a validation template.

  3. Specify the validation template, invoice report, and layout template to be associated with the bill unit.

  4. Load the business profile information into the BRM database by using the load_pin_business_profile utility. See "Loading Invoicing Business Profiles into the Database".

  5. If your system includes accounts that were created before you integrated BRM invoicing with Oracle Analytics Publisher, associate your existing /billinfo objects with /associated_bus_profile objects. See "Associating Pre-Existing Bill Units with Business Profiles".

Enabling the BRM-Oracle Analytics Publisher Integration

By default, BRM-Oracle Analytics Integration is disabled and invoices are stored in flist format. To use the BRM-Oracle Analytics integration, you must enable BRM-Oracle Analytics Integration and configure BRM to store invoices in XML format.

To enable the BRM-Oracle Analytics Publisher integration for invoices:

  1. Go to BRM_home/sys/data/config.

  2. Create an XML file from the /config/business_params object: 

    pin_bus_params -r BusParamsInvoicing bus_params_Invoicing.xml

  3. Enable integration by setting EnableInvoicingIntegration to enabled: 

    <EnableInvoicingIntegration>enabled</EnableInvoicingIntegration>

  4. Store invoices in XML format by setting InvoiceStorageType to 1: 

    <InvoiceStorageType>1</InvoiceStorageType>

  5. Save the file as bus_params_Invoicing.xml.

  6. Load the XML file into the BRM database:

    pin_bus_params bus_params_Invoicing.xml

  7. Stop and restart the CM.

For more information about pin_bus_params, see "pin_bus_params" in BRM Developer's Guide.

Loading Invoicing Business Profiles into the Database

After editing the pin_business_profile.xml file, use the load_pin_business_profile utility to load the contents of the file into /config/business_profile objects in the BRM database. For more information, see "Managing Business Profiles" in BRM Managing Customers.

Associating Pre-Existing Bill Units with Business Profiles

All /billinfo objects created before your BRM-Oracle Analytics Publisher integration are not linked to an /associated_business_profile object, which prevents you from creating Oracle Analytics Publisher invoices for those /billinfo objects.

To generate Oracle Analytics Publisher invoice documents for /billinfo objects created before the BRM-Oracle Analytics Publisher integration, you must run the pin_upd_assoc_bus_profile utility.

The pin_upd_assoc_bus_profile utility is a standalone multithreaded application (MTA) that performs the following operations:

  • Searches for /billinfo objects in the BRM database that have an empty PIN_FLD_ASSOC_BUS_PROFILE_OBJ_LIST field.

  • Creates an /associated_bus_profile object for each /billinfo object with an empty field.

  • Links the /billinfo object to its /associated_bus_profile object by populating the /billinfo object's PIN_FLD_ASSOC_BUS_PROFILE_OBJ_LIST field.

To associate pre-existing bill units with business profiles:

  1. Make sure that the BRM-Oracle Analytics Publisher integration is enabled. See "Enabling the BRM-Oracle Analytics Publisher Integration".

    Note:

    The utility fails if you attempt to run it when the BRM-Oracle Analytics Publisher integration is disabled.

  2. (Optional) To associate only a subset of your pre-existing bill units with business profiles, create a text file that specifies the /billinfo objects to update. The file must use the following format: 

    0 PIN_FLD_RESULTS     ARRAY [0] allocated 20, used 1
1    PIN_FLD_POID      POID [0] 0.0.0.1 /billinfo 37395 1
0 PIN_FLD_RESULTS     ARRAY [1] allocated 20, used 1
1    PIN_FLD_POID      POID [0] 0.0.0.1 /billinfo 37488 3

  3. Go to the BRM_home/apps/pin_billd directory.

  4. Enter the following command:

    pin_upd_assoc_bus_profile [-file filename]

    where filename specifies the name and location of the file that lists the /billinfo objects to update.

    Note:

    pin_upd_assoc_bus_profile requires a configuration file in the directory from which you run the utility. The configuration file requires the standard CM connection and MTA entries. See "Configuring Your Multithreaded Application" in BRM Developer's Guide.

If you run the utility without any parameters, the utility searches all /billinfo objects in the BRM database. If you run the utility with the -file parameter, the utility searches only those /billinfo objects specified in the file.

Viewing Invoices Individually on Oracle Analytics Publisher Console

In the BRM_Invoices reports directory (OAP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/Reports/BRM_Invoices/0.0.0n), the ViewInvoiceReport report is generated to view individually each invoice on the Oracle Analytics Publisher console.

Configure ViewInvoiceReport to point to the data source by editing the data model, configuring the data source, saving changes, and restarting Oracle Analytics Publisher. Enter the invoice POID for the input parameter and click Submit to see the report.

View the invoice on the console, by choosing the applicable template, such as Consumer Invoice, Corporate Invoice, Consumer Correction Invoice, Corporate Correction Invoice, Consumer Replacement Invoice, or Corporate Replacement Invoice.

Enabling the Display of Customer Details on the Web

By default, displaying contact details, account and bill numbers when using the Web is disabled in Oracle Analytics Publisher.

To enable the display of customer details on the Web:

  1. Go to the OAP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/Reports/BRM_Invoices/schema_number/schema_number.xdm directory.

  2. Open the _datamodel.xdm file in a text editor.

  3. Search for the following entry:

    <property name="include_rowsettag" value="false"/>

  4. Change false to true.

  5. Save and close the file.

Installing the BRM-Oracle Analytics Publisher Invoicing Integration Package

This section describes how to install the BRM-Oracle Analytics Publisher invoicing integration package. This package is set up on the Oracle Analytics Publisher server.

To install the BRM-Oracle Analytics Publisher invoicing integration package:

Note:

Install the BRM-Oracle Analytics Publisher invoicing integration package on the system on which BRM Reports is installed. If the BRM-Oracle Analytics Publisher invoicing integration package and BRM Reports are not installed on the same system, you cannot view an invoice in Oracle Analytics Publisher.

Preinstallation Requirements

The following must be completed before you run the BRM-Oracle Analytics Publisher invoicing integration package application:

  • Oracle Analytics Publisher is installed.

  • Oracle Analytics Publisher home environment variable has been successfully set.

For more information on these requirements, see BRM Reports.

Removing Older BRM-Oracle Analytics Publisher Invoicing Integration Layout Template Files

When you install the BRM-Oracle Analytics Publisher invoicing integration package, the older versions of BRM-Oracle Analytics Publisher invoicing integration layout template files are not automatically overwritten. Before installing the BRM-Oracle Analytics Publisher invoicing integration package, you must manually remove all previous versions of BRM-Oracle Analytics Publisher invoicing integration layout template files.

To remove older BRM-Oracle Analytics Publisher invoicing integration layout template files:

  1. Go to OAP_home/user_projects/domains/OAP_domain/config/bipublisher/repository/Reports/BRM_Invoices/SchemaNumber/BRM_Bursting_Invoice_Report.xdo/.

    where SchemaNumber is the directory for the BRM schema number to process BRM invoices; for example, 0.0.0.1.

  2. Manually remove the following layout template files:

    • BRM_Consumer_Correction_Invoice.rtf*

    • BRM_Consumer_Invoice.rtf*

    • BRM_Consumer_Replacement_Invoice.rtf*

    • BRM_Corporate_Correction_Invoice.rtf*

    • BRM_Corporate_Invoice.rtf*

    • BRM_Corporate_Replacement_Invoice.rtf*

  3. Go to OAP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/Reports/BRM_Invoices/SchemaNumber/ViewInvoiceReport.xdo/.

  4. Manually remove the following layout template files:

    • BRM_Consumer_Correction_Invoice_en_US.rtf*

    • BRM_Consumer_Invoice_en_US.rtf*

    • BRM_Consumer_Replacement_Invoice_en_US.rtf*

    • BRM_Corporate_Correction_Invoice_en_US.rtf*

    • BRM_Corporate_Invoice_en_US.rtf*

    • BRM_Corporate_Replacement_Invoice_en_US.rtf*

Install Billing and Invoicing Utilities

To install Billing and Invoicing Utilities, see "Installing Individual BRM Components" in BRM Installation Guide.

Installed Template Files

The BRM-Oracle Analytics Publisher invoicing integration program copies the templates listed in Table 12-1 to your computer's OAP_home/user_projects/domains/bifoundation_domain/config/bipublisher/repository/Reports/BRM_Invoices/SchemaNumber directory.

Table 12-1 Oracle Analytics Publisher-Related Files Placed on Your Computer

Templates Description

BRM_Consumer_Correction_Invoice.rtf

Layout template for consumer corrective invoice letter documents.

BRM_Consumer_Invoice.rtf

Layout template for consumer invoice documents.

BRM_Consumer_Replacement_Invoice.rtf

Layout template for consumer replacement invoice documents.

BRM_Corporate_Correction_Invoice.rtf

Layout template for corporate corrective invoice letter documents.

BRM_Corporate_Invoice.rtf

Layout template for corporate invoices.

BRM_Corporate_Replacement_Invoice.rtf

Layout template for corporate replacement invoice documents.

Configuring the pin_inv_doc_gen Utility

The pin_inv_doc_gen utility creates, delivers, and stores your invoice documents in the Oracle Analytics Publisher Scheduler database.

Configuring pin_inv_doc_gen involves:

Configuring the Infranet.properties File for pin_inv_doc_gen

The Infranet.properties file stores your network configuration entries for the pin_inv_doc_gen utility.

To configure the Infranet.properties file Oracle Analytics Publisher:

  1. Go to BRM_home/apps/pin_inv_doc_gen.

  2. Save the Infranet.properties.sample file as Infranet.properties.

    The Infranet.properties.sample file for the pin_inv_doc_gen utility includes the standard configuration entries. See "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

    Note:

    You must have read-write permissions to access the /invoice object. Your invoice data is stored in the /invoice object. The BRM system administrator creates this user and grants the required permissions.

  3. Open the Infranet.properties file in a text editor, and add your network entries and their values, as listed in Table 12-2.

    Table 12-2 Infranet.properties.sample File Entries

    Entry Description

    infranet.bip.password

    Specifies the password.

    Note: The password can be encrypted with Advanced Encryption Standard (AES) for security.

    infranet.bip.username

    Specifies the name of the Oracle Analytics Publisher server.

    infranet.bip.url

    Specifies the URL of Oracle Analytics Publisher in the following format:

    http://BIP_Hostname:Port/xmlpserver

    Note: Enable HTTPS and the SSL port for secure communication. See: "Configuring HTTPS for Secure Communication".

    infranet.burst.threadpool.chunksize

    Specifies the maximum number of BRM invoices per Oracle Analytics Publishing bursting query.

    infranet.burst.threadpool.maxsize

    Specifies the maximum number of concurrent threads in the pool.

    infranet.burst.threadpool.size

    Specifies the number of core threads in the pool.

    infranet.connection

    Specifies the URL to the BRM service.

    infranet.dmsearchargs.size

    Specifies the number of account and bill unit pairs the utility should process at one time.

    The maximum value is 14.

    infranet.dupinvdir.path

    Specifies the directory path for storing duplicate invoice documents.

    infranet.dupinvoice.watermark.angle

    Specifies the angle of the watermark text.The default value is 45 (angle of text is 45 degrees).

    See the Oracle Analytics Publisher Java API documentation.

    infranet.dupinvoice.watermark.colorr

    Specifies the red component of the watermark text color.

    The default value is 0.7f.

    infranet.dupinvoice.watermark.colorg

    Specifies the green component of the watermark text color.

    The default value is 0.7f.

    infranet.dupinvoice.watermark.colorb

    Specifies the blue component of the watermark text color.

    The default value is 0.7f.

    infranet.dupinvoice.watermark.coordx

    Specifies the x-coordinate of the start of the watermark text.

    The default value is 200f (starting coordinate lower left x).

    infranet.dupinvoice.watermark.coordy

    Specifies the y-coordinate of the start of the watermark text.

    The default value is 250f (starting coordinate lower left y).

    infranet.dupinvoice.watermark.font

    Specifies the font of the watermark text.

    The default value is Arial.

    infranet.dupinvoice.watermark.fontsize

    Specifies the size of the watermark text.

    The default value is 48.

    infranet.dupinvoice.watermark.text

    Specifies the text to be displayed as the background watermark in the duplicate invoice.

    The default value is DUPLICATE.

    infranet.schedulerdb.url

    Specifies the scheduler database URL in the following format:

    jdbc:oracle:thin:@protocol://hostname:port/service

    where protocol is either tcp or tcps, hostname is the hostname of the scheduler database, port is the port number for the scheduler database, and service is the service name of the scheduler database.

    infranet.schedulerdb.user

    Specifies the user name for the scheduler database.

    infranet.schedulerdb.credentials

    Specifies the security credentials for connecting to the scheduler database.

    infranet.jdbcpool.size

    Specifies the initial number of connections maintained in the pool.

    The default is set to the same as burst.threadpool.size.

    infranet.jdbcpool.maxsize

    Specifies the maximum number of connections that can be created.

    The default is set to the same as burst.threadpool.maxsize.

    infranet.http.notification.server

    Specifies the name of the HTTP server used for notifications.

    Important: Enable HTTP notifications in Oracle Analytics Publisher. See the Oracle Analytics Publisher documentation for details.

    infranet.http.notification.userName

    Specifies the HTTP server login name.

    infranet.http.notification.password

    Specifies the HTTP server login password.

    infranet.log.file

    Specifies the log file name for the pin_inv_doc_gen utility.

    infranet.log.level

    Specifies the level of log for the pin_inv_doc_gen utility.

    infranet.login.type

    Specifies the type of login. A type 1 login requires the application to provide a user name and password. A type 0 login is a trusted login that comes through a Connection Manager (CM) proxy. It doesn't require a user name or password. Use 1 or 0.

    infranet.notify.http.when.success

    Specifies whether to receive HTTP notification when an Oracle Analytics Publisher job is successful. By default, HTTP notification is enabled and set to true. To disable HTTP notification, set this entry to false.

    infranet.notify.http.when.warning

    Specifies whether to receive HTTP notification when an Oracle Analytics Publisher job contains warnings. By default, HTTP notification is enabled and set to true. To disable HTTP notification, set this entry to false.

    infranet.polling.sleeptime

    Specifies the sleep time (in milliseconds) between polling calls while waiting for the Oracle Analytics Publisher schedule to complete. The default value is 5000 (5 seconds).

    infranet.threadpool.fetchsize

    Specifies the number of records that can be fetched by the thread. The default value is 5.

    infranet.threadpool.maxsize

    Specifies the maximum number of threads. The default value is 5.

    infranet.threadpool.size

    Specifies the number of threads. The default value is 3.

  4. Save and close the file.

Configuring the docgen.sh Batch Script

The docgen.sh batch script is used for setting environment variables and launching the pin_inv_doc_gen utility.

To configure the docgen.sh batch script:

  1. Go to the BRM_home/apps/pin_inv_doc_gen directory.

  2. Open the docgen.sh batch script in a text editor.

  3. Edit the default values available in the file to the values specific to your system environment.

    Note:

    The pin_inv_doc_gen utility runs only in the 32-bit mode. Set the Java executable in the docgen.sh file to the 32-bit Java version.

  4. Save and close the file.

Changing Command-Line Parameters for pin_inv_doc_gen

To change the command-line parameters for pin_inv_doc_gen utility, you update the docgen.sh batch script:

  1. Go to the BRM_home/apps/pin_inv_doc_gen directory.

  2. Open the docgen.sh batch script in a text editor.

  3. Search for the following line:

    invoicedocgen.pin_inv_doc_gen -status pending

  4. Add or replace the pin_inv_doc_gen command-line parameter with the required parameter. For syntax and parameter usage, see "pin_inv_doc_gen".

  5. Save and close the file.

  6. In the command prompt, navigate to the BRM_home/apps/pin_inv_doc_gen directory.

  7. Enter the following command which runs the docgen.sh batch script: 

    docgen.sh

    The pin_inv_doc_gen utility runs with the updated command-line parameter.

Setting Scheduler Configuration

To set scheduler configuration, see the discussion of setting scheduler configuration options in the Oracle Analytics Publisher documentation.

Configuring the Email Server

To configure the email server in Oracle Analytics Publisher, see the discussion of setting up delivery options in the Oracle Analytics Publisher documentation.

Configuring HTTPS for Secure Communication

Oracle Analytics Publisher can be configured to support HTTPS for secure communication. In addition to setting up HTTPS in Oracle Analytics Publisher, you also configure the Infranet.properties file and pin_inv_doc_gen utility.

To configure HTTPS for secure communication:

  1. Enable HTTPS in Oracle Analytics Publisher. For more information, see the Oracle Analytics Publisher documentation.

  2. Open the Infranet.properties file in a text editor.

  3. Add the following line:

    infranet.bip.url=https://BIP_Hostname:SSL_port/xmlpserver

    where:

    • BIP_Hostname is the host name on which the Oracle Analytics Publisher server is installed.

    • SSL_port is your secure sockets layer port number.

  4. Save and close the file.

  5. In the command prompt, navigate to the BRM_home/apps/pin_inv_doc_gen directory.

  6. Enter the following command which runs the docgen.sh batch script: 

    docgen.sh

    The pin_inv_doc_gen utility runs with the updated URLs.

  7. Enter yes for: 

    Is it a trusted certificate?
Creating the XMLP_INVOICE_JOB Table in the Scheduler Database

The XMLP_INVOICE_JOB table stores the mapping of the job ID to the Invoice_POID for which an invoice document is generated.

To create the XMLP_INVOICE_JOB table in the Scheduler database:

  1. Go to BRM_home/apps/pin_inv_doc_gen.

  2. Open the Create_Xmlp_Invoice_Job.sql file.

  3. Search for <tablespacename>.

  4. Replace <tablespacename> with the tablespace name where all the Scheduler tables in the Oracle Analytics Publisher Scheduler database are created.

  5. Save and close the file.

  6. In a terminal, enter the following command to open SQL*Plus: 

    sqlplus user_name@Database_Name
Enter password: password

    where:

    • user_name is the user name for the Scheduler database.

    • password is the password for the Scheduler database.

    • Database_Name is the SID of the Scheduler database.

  7. At the SQL prompt, enter the following command:

    SQL> @Create_Xmlp_Invoice_Job.sql

  8. Configure the Java Naming and Directory Interface (JNDI) for invoiceXREF to allow the pin_inv_doc_gen utility to connect to the Scheduler database:

    1. Log on to the Oracle WebLogic Console.

    2. Click Services.

    3. Click Data Sources.

    4. Click the Lock and Edit button.

    5. Create a new data source.

    6. Enter JNDI details:

      Name=invoiceXREF

      JNDI name= jdbc/OracleBRM/invoiceXREF

    7. Click Next.

    8. Enter the Scheduler database details that you used when you installed the XMLP_INVOICE_JOB table.

    9. Click Next.

    10. Select the server on which the Oracle Analytics Publisher software is installed.

    11. Click Finish.

    12. Click Activate Changes.

    13. Stop and restart the Oracle Analytics Publisher server.

Configuring the BRM-Oracle Analytics Publisher Invoicing Integration to Support Multischema Systems

To configure the BRM-Oracle Analytics Publisher invoicing integration to support multischema systems, do the following:

Loading Stored Procedures

To load stored procedures, do the following:

  1. Go to BRM_home/apps/pin_inv_doc_gen

  2. Open SQL*Plus at the command line:

    sqlplus user_name@Database_Name
Enter password: password

  3. Enter the following command:

    SQL>@invoice_bursting.plb

  4. Type exit to quit SQL*Plus.

Creating New JDBC Data Sources

The BRM-Oracle Analytics Publisher invoicing integration packages invoicing reports and the data model for BRM primary schema. To create new JDBC sources to support BRM multischema, you follow these procedures. For more information, refer to the Oracle Analytics Publisher documentation.

Creating Data Source for Each BRM Schema

To create a data source for each BRM schema:

  1. In a Web browser, enter the following URL:

    http://OAP_host:port/xmlpserver/

    where:

    • OAP_host is the host name on which the Oracle Analytics Publisher server is installed.

    • port is the console port. The default port is 9704.

      The Oracle Analytics Publisher Enterprise client opens.

  2. On the global header, click Administration.

  3. Under Data Sources, click JDBC Connection.

  4. On the JDBC page, click the Add Data Source button.

  5. Enter the following database connection details for the BRM schema:

    • In the Data Source Name field, enter a name, for example, BRM_DATA_SOURCE.

    • In the Driver Type field, enter Oracle 12c.

    • In the Database Driver Class field, enter oracle.jdbc.OracleDriver.

    • In the Connection String field, enter your database connection details. For example:

      jdbc:oracle:thin:@Hostname:port:SID

      where Hostname is the host name for the database that contains the secondary schema.

    • In the Username field, enter the BRM schema user name.
    • In the Password field, enter the password for the BRM schema user.

  6. Click Test Connection, which verifies the connection to BRM schema.

    A confirmation message is displayed.

  7. Click Apply, which saves your changes.

  8. Repeat the previous steps for each schema.

Setting Up the Data Model Configuration for Multischema

To configure invoices for multischema:

  1. In the BRM_Invoices reports directory, copy reports directory 0.0.0.1 to 0.0.0.n.

  2. Rename the data model directory within 0.0.0.n. For example, to set up the data model configuration for 0.0.0.2, do the following: 

    cd OAP_home/user_projects/domains/OAP_domain/config/bipublisher/repository/Reports/BRM_Invoices
cp -r 0.0.0.1 0.0.0.2
cd 0.0.0.2
mv 0.0.0.1.xdm 0.0.0.2.xdm

  3. Edit the data source name specified in "Creating Data Source for Each BRM Schema".

    For example, in 0.0.0.2/0.0.0.2.xdm/ _datamodel.xdm, enter the data source name in defaultDataSourceRef and the BRM schema number in CDATA.

  4. Set the URL of the BRM bursting report data model to the secondary schema by modifying dataModel URL in 0.0.0.2/BRM_Bursting_Invoice_Report.xdo/_report.xdo.

  5. To configure pin_inv_doc_gen for multischema changes, edit the docgen.sh batch script. For example, you add -schema 0.0.0.n where n is the schema number after the -status pending flag of each schema.

    Note:

    The -schema 0.0.0.n parameter is optional. If it is not specified, schema information comes from the infranet.connection value in the Infranet.properties configuration file; the default is 0.0.0.1.