15 Invoice Utilities

Learn about the invoice utilities provided with Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

• load_pin_invoice_data_map

• pin_inv_accts

• pin_inv_doc_gen

• pin_inv_export

• pin_inv_send

• pin_load_invoice_events

• pin_load_invoice_template

• pin_upd_assoc_bus_profile

load_pin_invoice_data_map

Use this utility to load invoice data templates into the /config/invoice_data_map object in the BRM database. You define the invoice data template in the BRM_home/data/config/pin_invoice_data_map file.

For more information, see "Including Invoice Data from Custom Applications".

Location

BRM_home/bin

Syntax

load_pin_invoice_data_map [-d] [-v] [-h] invoice_data_map_file

Parameters

-d

Creates a log file for debugging purposes. Use this parameter when the utility appears to have run with no errors but the invoice data templates have not been loaded into the database.

-v

Displays information about successful or failed processing as the utility runs.

To redirect the output to a log file, use the following command. Replace filename.log with the name of the log file:

load_pin_invoice_data_map -v > filename.log

Note:

If a file with the same name exists, it is overwritten.

-h

Displays the syntax and parameters for this utility.

invoice_data_map_file

The name and location of the file that defines invoice data templates. The default pin_invoice_data_map file is in the BRM_home/sys/data/config directory.

If you copy the pin_invoice_data_map file to the same directory from which you run the load_pin_invoice_data_map utility, you do not need to specify the path or the file name.

If you use the default pin_invoice_data_map file name, you do not need to specify it on the command line when it is located in the same directory as this utility.

Results

The load_pin_invoice_data_map utility notifies you only if it encounters errors.

Note:

You must restart the Connection Manager (CM) to make new invoice data templates available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

pin_inv_accts

Use this utility to generate regular invoices and corrective invoices. For regular invoices, run this utility as part of your daily billing to create an invoice for each account that is billed on that day.

Note:

• For regular invoices, you typically run pin_inv_accts as part of pin_bill_day, the daily billing script. If you run invoicing separately from pin_bill_day, you must run pin_bill_accts before you run pin_inv_accts. For more information on generating regular invoices, see "About Invoicing".

• For corrective invoices, run this utility after you have generated the necessary corrective bills. For more information, see "About Corrective Invoices".

For information on pin_bill_day, see "About Running the Billing Scripts" in BRM Configuring and Running Billing.

Location

BRM_home/bin

Syntax

pin_inv_accts [-test] [-start startDate] [-end endDate] [-regen]
              [-corr_bills -reg_bills -corr_type replacement|correction]                 
              [-summary|-detail] [-pay_type id|-hierarchy|-file filename]                 
              [-skip_blank_billnos] [-verbose] [-help] 

Parameters

-test

Runs a test to find out how many accounts meet the criteria without performing the action. The test has no effect on the accounts. This is most useful when run with the -verbose option.

-start startDate

-end endDate

Generates invoices for accounts whose billing cycle ended during the time period defined by startDate and endDate, including the endDate.

If you do not specify an endDate, pin_inv_accts uses the current date. If you do not specify a startDate, pin_inv_accts searches for all invoices that you have not already sent.

You can specify the date in either of two formats:

• MM/DD/YY

• -N, where N is the number of days before the current date.

-regen

Regenerates previously created invoices in a different format.

To regenerate invoices within a specified date range, use the -start and ‐end parameters. If you do not include start and end dates, pin_inv_accts regenerates all invoices in the database that are not already stored in the specified format.

To regenerate invoices for nonpaying child bills in a bill unit hierarchy, run the pin_inv_accts utility with the -regen and -hierarchy parameters. By default, invoices are regenerated only for parent bills in a bill unit hierarchy and for paying nonhierarchical bills.

Note:

You can regenerate invoices only if you still have all the original /event and /bill objects for the months you want to regenerate. If the balances are maintained correctly in the /bill objects and are not updated, you can regenerate invoices.

-corr_bills

Generates corrective invoices for corrective bills. The type of corrective invoice it generates depends on the input for -corr_type. Additionally, whether the utility generates a summary or detailed corrective invoice document depends on whether -summary or -detail parameter is set in the input.

• If the -summary parameter is set, the pin_inv_acctsutility generates a summary Replacement Invoice when the input parameter is -corr_type replacement and a summary Invoice Correction Letter when the input parameter is -corr_type correction. (As stated earlier, if you did not provide any input for the -corr_type parameter, the pin_inv_accts utility uses the current value for the corrective invoice type stored with the corrective bill.)

• If the -detail parameter is set, the pin_inv_acctsutility generates a detailed Replacement Invoice when the input parameter is -corr_type replacement and a detailed Invoice Correction Letter when the input parameter is -corr_type correction. (As stated earlier, if you did not provide any input for the -corr_type parameter, the pin_inv_accts utility uses the current value for the corrective invoice type stored with the corrective bill.)

-reg_bills

Generates regular invoices for regular bills (that is, bills that have no corrections). Generates summary invoice if -summary parameter is set; generates detailed invoice if -detail parameter is set. If you do not specify any of these parameters, pin_inv_accts uses -detail parameter.

-corr_type replacement|correction

Generates replacement invoices if the -corr_type replacement parameter is set, and generates invoice correction letters if the -corr_type correction parameter is set.

If you do not specify any of these parameters, pin_inv_accts uses the current value for the corrective invoice type stored with the corrective bill.

-summary|-detail

Generates summary invoices if the -summary parameter is set; generates detailed invoices if the -detail parameter is set.

• For regular invoices, if you do not specify any of these parameters, pin_inv_accts uses -detail parameter.

• For corrective invoices, if you do not specify any of these parameters, pin_inv_accts uses the current value for the corrective invoice type stored with the corrective bill.

Note:

If you generate both regular and corrective invoices in the same run, BRM generates the same type of invoices (summary or detailed).

If you need to generate one set of invoices as summaries and another set of invoices in detail, run pin_inv_accts twice, once for regular invoices and once for corrective invoices.

-pay_type id

Generates invoices only for accounts with the specified payment method ID. If you do not specify this parameter, pin_inv_accts generates invoices for all payment methods.

Use one payment method ID from Table 15-1.

Table 15-1 Payment Method IDs

Payment Method	ID
undefined	0
prepaid	10000
invoice	10001
debit	10002
credit card	10003
direct debit	10005
smart card	10006
nonpaying	10007
beta	10008
internal	10009
guest	10010
cash	10011
check	10012
wire transfer	10013
payorder	10014
postal order	10015
voucher	10016
SEPA	10018

For example, to generate invoices for all bills paid by the check payment method, use this syntax:

pin_inv_accts -paytype 10012

For more information, see "About Payment Methods" in BRM Configuring and Collecting Payments.

-hierarchy

Retrieves bills for paying bill units in which the bill's PIN_FLD_AR_HIERARCHY_SIZE value exceeds the invoicing threshold and generates a separate invoice for each nonpaying bill unit (/billinfo object).

See "Invoicing for Hierarchical Bill Units".

-file filename

Generates an invoice for each bill in the specified file. For example:

pin_inv_accts -file bills_020207

Note:

The file must be in pin_flist format, which is the internal BRM data structure. 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 on the pin_flist format, see "About Formats for Storing Invoices".

-skip_blank_billnos

Excludes invoicing for nonpaying bill units that do not contain bill numbers.

Nonpaying bill units, which use the bill number of their paying parent bill unit, are generated even when billing for the parent bill unit is suppressed. In such cases, they will not contain bill numbers, which invoices require. Therefore, when bill suppression is enabled on an account that owns a paying parent bill unit, and the nonpaying bill unit threshold is exceeded (multiple threads are used to process the invoices), invoicing fails because the parent bill number is not available. This parameter enables pin_inv_accts to proceed without processing those bill units.

(Nonpaying bill units contain bill numbers only when their paying parent bill unit is billed.)

-verbose

Displays information about successful or failed processing as the utility runs.

Note:

This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -verbose at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file:

pin_inv_accts any_other_parameter -verbose > filename.log

-help

Displays the syntax and parameters for this utility.

Results

When it is called internally by the pin_bill_day script, the pin_inv_accts utility logs error information in the pin_inv.pinlog file.

pin_inv_doc_gen

Use this utility to create, deliver, and store invoice documents in the Oracle Business Intelligence Publisher (BI Publisher) Scheduler database.

After /invoice objects are created by running the pin_inv_accts utility, run the pin_inv_doc_gen utility on the BI Publisher server to generate the invoice document.

Start the pin_inv_doc_gen utility by running the docgen.sh script on the server running Oracle WebLogic Server. For information on the docgen.sh script, see "Generating BI Publisher Invoice Documents in BI Publisher".

Set the infranet.dmsearchargs.size parameter in the Infranet.properties configuration file to the number of account and bill unit pairs the utility processes at one time. The maximum value for infranet.dmsearchargs.size is 14.

For example, if the InvoiceList.xml file lists 20 account and bill unit pairs, and infranet.dmsearchargs.size is set to 6, the pin_inv_doc_gen utility processes six account and bill unit pairs at a time.

For more information on generating invoices with BI Publisher, see "Designing and Generating Invoices in Oracle Business Intelligence Publisher".

Note:

• Before running the pin_inv_doc_gen utility, save the BRM_home/apps/pin_inv_doc_gen/Infranet.properties.sample configuration file as Infranet.properties.

• To connect to the BRM database, run pin_inv_doc_gen from the directory that contains the Infranet.properties configuration file.

• BI Publisher supports multischema systems.

For more information, see "Configuring the Infranet.properties File for pin_inv_doc_gen with BI Publisher".

Location

BRM_home/apps/pin_inv_doc_gen

Syntax

pin_inv_doc_gen [-accts_list InvoiceList.xml|-type [-consumer|-corporate]
                [-schema SchemaNumber][-status pending|generated]
                [-start startDate][-end endDate][-help]

Parameters

You must specify at least one parameter. The parameters -accts_list and -type are mutually exclusive. The parameters -status and -start, -end are valid only if included along with other parameters. The parameter -schema is valid only with BI Publisher.

-accts_list InvoiceList.xml

InvoiceList.xml specifies the list of all the account and bill unit pairs for which an /invoice object is generated and stored in the BRM database, and for which an invoice document is not yet generated.

-type

Specifies the type of account for which the invoice document is to be generated:

• -type consumer generates a consumer account.

• -type corporate generates a corporate account. For a corporate account, all the /invoice objects of its child accounts that have nonpaying bill units (if they have a separate /invoice POID) are selected for generating the invoice document. See "Invoicing for Hierarchical Bill Units". However, the /invoice object of the child account that has a paying bill unit is not selected for generating invoice documents of a corporate type.

The -type parameter maps to the PIN_FLD_PARENT_FLAGS field of the /billinfo object of the /invoice object. For consumer accounts, the PIN_FLD_PARENT_FLAGS field value is 0. For corporate accounts, which own the paying parent bill unit in the bill unit hierarchy, the PIN_FLD_PARENT_FLAGS field value is greater than zero.

-schema SchemaNumber

(Valid only for BI Publisher 11g and 12c) Generates the BRM schema number, in the format 0.0.0.n, for processing BRM invoices. For example,

-schema 0.0.0.2

processes the BRM invoices in schema 0.0.0.2.

If the schema number is not specified, it defaults to 0.0.0.1.

For more information, see "Configuring the BRM-BI Publisher Invoicing Integration to Support Multischema Systems".

-status

Specifies the status of the /invoice object for which the invoice is to be generated:

• -status pending selects the /invoice objects for a document that has not been generated. It selects /invoice objects with a status of 0 and generates documents for them.

• -status generated generates duplicate documents for invoices for a document that has been generated. The duplicate document displays a Duplicate watermark on the document. For more information, see "Generating Duplicate Invoice Documents with BI Publisher".

-start startDate

-end endDate

Generates invoice documents for accounts or bill units whose /invoice objects were created during the time period defined by startDate and endDate.

If you do not specify a start date, pin_inv_doc_gen fetches all /invoice objects with a status of PIN_INV_STATUS_PENDING.

If you do not specify an end date, pin_inv_doc_gen uses the current date. The end date cannot be greater than the current date. The end date specified is inclusive, which means all /invoice objects created until 23:59:59 of the end date are selected by the search query.

Specify the date in MM/DD/YYYY format.

-help

Displays the syntax and parameters for this utility.

pin_inv_export

Use this utility to export invoices to a format you can use with other programs, such as DOC1. This command-line utility retrieves invoices from the BRM database and saves them as files.

You specify the format and directory for the invoice files in the invoice utility configuration file. For more information, see "Exporting Invoices" and the instructions in the invoicing configuration file.

The pin_inv_export utility generates file names automatically with an inv prefix.

Note:

For nonpaying child bill invoices that are not consolidated into the parent invoice, pin_inv_export creates a separate invoice file for each nonpaying child bill. The file naming convention is:

inv_BillPOID_BillDate_NonpayingChildAccountPOID_ARaccountPOID.ext

For nonpaying child bill invoices that are consolidated into the parent invoice and are exported as an individual invoice, the file name will not contain the parent account POID. Instead, it will be in the format:

inv_BillPOID_BillDate_NonpayingChildAccountPOID.ext

Location

BRM_home/bin

Syntax

pin_inv_export [-start startDate] [-end endDate] [ -trial | -detail filename] [-verbose] [-help] 

Parameters

-start startDate

-end endDate

Retrieves invoices for accounts whose billing cycle ended during the time period defined by startDate and endDate, including the endDate.

If you do not specify an end date, pin_inv_export uses the current date. If you do not specify a start date and an end date, pin_inv_export creates a file for every invoice in the database.

You can specify the date in either of two formats:

• MM/DD/YY

• -N, where N is the number of days before the current date.

For example:

pin_inv_export -verbose -start 01/01/09 -end 01/10/09

pin_inv_export -verbose -start -10, sets the start date to 10 days before the current date and the end date to the current date.

-trial

Exports trial invoices (/invoice/trial).

Note:

If a custom /invoice storable subclass exits, invoices of type /invoice/.../trial are exported.

-detail filename

Exports detailed invoices for the bills listed in the specified file. This parameter overrides the PIN_FLD_INV_TYPE value specified in the /payinfo object associated with the bill.

The file must be in pin_flist format and can contain any number of bills. 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 on generating a pin_flist file of bills, see "pin_inv_accts".

-verbose

Displays information about successful or failed processing as the utility runs.

Note:

This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -verbose at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter.

pin_inv_export any_other_parameter –verbose > filename.log

where filename is the name of the log file.

-help

Displays the syntax and parameters for this utility.

pin_inv_send

Use this utility to email or print invoices depending on the delivery method specified in a customer's account (Email or Postal).

You can configure the following behavior by editing the pin_inv_send utility's configuration file (BRM_home/apps/pin_inv/pin.conf).

• To set the maximum size in kilobytes of invoices that can be sent by email, set the inv_send_size entry. This entry is used to restrict sending large invoices to the Email Data Manager (dm_email).

• To send individual nonpaying child bill invoices to the email address of the parent A/R bill, set the send_sub_inv_2_parent entry.

The Email Data Manager must be running when you run this utility, even for printing. For information, see "Sending Email to Customers Automatically" in BRM Managing Customers and "Configuring the Email Data Manager for Printing".

For more information about sending invoices, see "Sending Invoices to Customers".

Location

BRM_home/bin

Syntax

pin_inv_send    [-start startDate] [-end endDate] [‐pay_type id] 
                [-format_id id] [-v] [-h] 

Parameters

-start startDate

-end endDate

Emails or prints invoices for accounts with invoices whose billing cycle ended during the time period defined by the startDate and endDate, including the endDate.

If you do not specify an end date, pin_inv_send uses the current date. If you do not specify a start date, pin_inv_send searches for all invoices that you have not already sent.

You can specify the date in either of two ways:

• MM/DD/YY

• -N, where N is the number of days before the current date.

-pay_type id

Emails or prints invoices only for accounts with the specified payment method. If you do not specify this parameter, pin_inv_send emails or prints invoices for invoice payment methods only.

Use one payment method ID from Table 15-2.

Table 15-2 Payment Method IDs

Payment Method	ID
undefined	0
prepaid	10000
invoice	10001
debit	10002
credit card	10003
direct debit	10005
smart card	10006
nonpaying	10007
beta	10008
internal	10009
guest	10010
cash	10011
check	10012
wire transfer	10013
payorder	10014
postal order	10015
voucher	10016
SEPA	10018

For example, to email or print invoices for all bills paid by the check payment method, enter this command:

pin_inv_send -pay_type 10012

For more information on payment methods, see "About Payment Methods" in BRM Configuring and Collecting Payments.

-format_id id

Specifies the invoice's format. By default, pin_inv_send mails invoices in HTML format. Use this parameter to use DOC1 format instead. The format ID can have the values shown in Table 15-3.

Table 15-3 Format ID Values

Format	ID
HTML	1
DOC1	3

-v

Displays information about successful or failed processing as the utility runs.

Note:

This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -v at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file:

pin_inv_send any_other_parameter –v > filename.log

-h

Displays the syntax and parameters for this utility.

pin_load_invoice_events

Use this utility to load a list of the events that you want to include on invoices into a /config/invoice_events object.

Location

BRM_home/bin

Syntax

pin_load_invoice_events  [-brand "0.0.0.1/account 1"] [-eventfile file] 
                         [-logfile logfile] [-reload] [-debug] [-help]

Parameters

-brand "0.0.0.1/account 1"

Specifies the root POID.

Note:

The quotation marks are required.

-eventfile file

Specifies the path name of the event file. The events in the file should be listed one per line. For example:

/event/billing/adjustment/account

/event/billing/adjustment/event

/event/billing/adjustment/item

/event/billing/adjustment/tax_event

/event/billing/cycle/tax

/event/billing/payment/cash

/event/billing/payment/cc

...

-logfile logfile

Specifies the full path name of the log file.

-reload

Reloads an existing /config object.

-debug

Logs the flist and detailed messages in the log file.

-help

Displays the syntax and parameters for this utility.

Results

The pin_load_invoice_events utility should notify you that it was successful. If errors are returned, look in the utility log file (default.pinlog) for detailed error messages. The log file is located either in the directory from which the utility was started or in a directory specified in the configuration file.

pin_load_invoice_template

Use this utility to load the invoice template into the BRM database or to change the flag that specifies whether to use an HTML template or an XSL style sheet for an existing template object.

For information about creating invoice templates, see "Designing Invoices".

Location

BRM_home/bin

Syntax

pin_load_invoice_template  [-brand "0.0.0.1/account 1"] [-type template_type]
                           [-locale locale_string] [-template template_file]                            
                           [-usexsl] [-debug] [-logfile logfile] [-help]

Parameters

-brand "0.0.0.1/account 1"

Specifies the root POID.

Note:

The quotation marks are required.

-type template_type

Specifies the template type. To use an HTML template, specify "HTML". To use an XSL style sheet, specify a mime type, for example, "text/html".

Note:

The -template option must specify a file containing a template of the same type you specify in this option.

-locale locale_string

Specifies the locale such as, en_US.

-template template_file

Specifies the full pathname of the template file.

-usexsl

Uses the XSL invoice formatting opcode. This option sets the PIN_FLD_FLAG field in the /config/invoice_templates object to XSL style sheets.

-debug

Logs the flist and detailed messages in the log file.

-logfile logfile

Specifies the full path name of the log file.

-help

Displays the syntax and parameters for this utility.

Changing the Template Flag

To change the flag that specifies whether to use an HTML template or an XSL style sheet, set the PIN_FLD_FLAGS field in the /config/invoice_templates object by using this syntax:

• For an HTML template:

  pin_load_invoice_template -brand "0.0.0.1/account 1"

• For an XSL style sheet:

  pin_load_invoice_template -brand "0.0.0.1/account 1" [-usexsl]

  When the -usexsl option is not specified, an HTML template will be used.

Results

The pin_load_invoice_template utility should notify you that it was successful. If errors are returned, look in the utility log file (default.pinlog) for detailed error messages. The log file is located either in the directory from which the utility was started or in a directory specified in the configuration file.

pin_upd_assoc_bus_profile

Use this utility to associate bill units with an invoicing business profile. It searches the BRM database for /billinfo objects with an empty PIN_FLD_ASSOC_BUS_PROFILE_OBJ_LIST field and populates the field with an /associated_bus_profile object. See "Associating Pre-Existing Bill Units with Business Profiles".

Before running pin_upd_assoc_bus_profile, you must:

• Load invoicing business profiles into the database. See "Loading Invoicing Business Profiles into the Database".

• Enable the BRM-BI Publisher integration framework. This utility fails if you attempt to run it when the BRM-BI Publisher integration framework is disabled. See "Enabling the BRM-BI Publisher Integration".

Note:

The pin_upd_assoc_bus_profile utility needs the configuration file in BRM_home/apps/pin_billd. This configuration file must be present in the directory from which you run the utility.

Because pin_upd_assoc_bus_profile is based on the BRM multithreaded application (MTA) framework, the configuration file also requires some performance-related configuration entries. For more information, see "Configuring Your Multithreaded Application" in BRM Developer's Guide.

Location

BRM_home/bin

Syntax

pin_upd_assoc_bus_profile  [-file filename] [–verbose] [–help]

Parameters

-file filename

Specifies the name and location of the input file that lists the /billinfo objects to update. This is an optional parameter.

The input file should be in 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

-verbose

Displays information about successful or failed processing as the utility runs.

-help

Displays the syntax and parameters for this utility.