Chapter 17

Understanding XML Publisher Invoices

This chapter provides an overview of XML Publisher invoice structure and XML Publisher invoice setup, and discusses how to create new XML Publisher invoices.

Understanding XML Publisher Invoice Structure

XML Publisher is part of the Oracle technology stack. It enables you to create and customize reports using templates. These templates are maintainable using standard desktop applications such as Microsoft Word, Microsoft Excel, and Adobe Acrobat. It is fairly simple to create and maintain these templates because these applications are familiar tools. The XML Publisher engine takes XML data as input, combines it with the report template, and translates it to produce the report output. The report output can be HTML, PDF, RTF, or XLS. Similar to Crystal invoices, XML Publisher invoices do not use the invoice Form ID to determine where to place data on the page. For example, when determining where to print header notes. With XML Publisher invoices, this type of information is determined by the XML Publisher report definition or template. XML Publisher invoices receive data from the extract tables. An XML Publisher invoice had four elements associated to it: a data source, a report definition, a report template, and a file layout. Two sample templates are delivered with PeopleSoft Billing for printing invoices using XML Publisher. One template is for consolidated invoices and the other template is for non-consolidated invoices. These templates are RTF templates that were created using Microsoft Word and the XML Publisher Template Builder, which is a plug-in to Microsoft Word. You can use the delivered templates, create new templates, or modify the existing templates. The sample templates include special processing to handle invoices with this type of data: VAT and sales tax information. Forward balance amount. Paid amount. Credit card payment. Deposit invoice (from a sales order). The sample invoices do not support summarized invoices, Acceptgiro invoices, PeopleSoft Project Costing and Contracts invoices, PeopleSoft Grants and Order Management invoices, or installment invoices. If there is a need to print these types of invoices, then a new report must be created or the sample reports can be modified. Note. It is recommended that these invoices be printed in PDF for the highest quality.

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

485

Understanding XML Publisher Invoices

Chapter 17

See Also Enterprise PeopleTools 8.50 PeopleBook: XML Publisher for PeopleSoft Enterprise

Understanding XML Publisher Invoice Setup

PeopleSoft Billing delivers two sample invoice templates. Each template has a data source associated to it. A data source defines how the XML data will be generated. Two data sources are delivered for producing invoices: BI_INVOICE_DATA and BI_INVOICE_DATA_CONS. Both of these data sources are set up as XML File sources, which means that in Billing, an XML File will be generated and will serve as the input to the PeopleTools APIs for XML Publisher. The invoice data that gets populated into the XML File is determined by the file layout that is associated with the Billing batch-printing program. Two batch-printing programs are delivered, which are Application Engine programs: BI_PRNXPN01 and BI_PRNXPC01. These batch processes are initiated from the same components as the SQR and Crystal printing processes. In addition to the two data sources, PeopleSoft Billing delivers two report definitions: BI_PRNXPN01 for printing non-consolidated invoices, and BI_PRNXPC01 for printing consolidated invoices. Both report definitions have a template defined. This table shows all of the elements that are delivered in the XML Publisher invoice solution:
Invoice Data Source Report Definition Template File Layout Application Engine Program

Non-consolidated invoices Consolidated invoices

BI_INVOICE_D ATA BI_INVOICE_D ATA_CONS

BI_PRNXPN01

BI_PRNXPN01_ ENG.RTF BI_PRNXPC01_ ENG.RTF

BI_EXTRCT

BI_PRNXPN01

BI_PRNXPC01

BI_EXTRCT_C ONS

BI_PRNXPC01

Note. In the delivered sample template for consolidated invoices, each invoice that is attached is displayed as a group of lines with a subtotal. Unlike the SQR consolidated invoices that print each attached invoice on a separate page. However, you can modify the template, or create a new template to give your report a unique appearance. In addition to the two sample invoices, an invoice format for the government standard form 1034/1035 is also delivered.
Invoice Data Source Report Definition Template File Layout Application Engine Program

SF1035/1035

BI_103X_DATA

BI_XPSF103X

BI_XPSF103X_E BI_EXTRCT_SF NG_DETAIL.rtf 103X BI_XPSF103X_E NG_SUMMARY .rtf

BI_XPSF103X

486

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

Chapter 17

Understanding XML Publisher Invoices

Creating New XML Publisher Invoices

The process of creating new invoice reports is dependant on how extensive the changes are. If only a change in format is required, and additional fields are not required, then you can modify the delivered templates, or you can make a copy of the delivered templates and make changes to the copied version. Alternatively, you can create a new template from scratch. To create new XML Publisher Invoices: 1. Create a new data source. 2. Create or modify a template. 3. Upload a new template in PeopleSoft. 4. Create or modify a file layout. 5. Create a new Application Engine shell program. 6. Add a new invoice form.

Pages Used to Create New XML Publisher Reports

Page Name Definition Name
PSXPDATASRC

Navigation

Usage

Data Source

Reporting Tools, XML Publisher, Data Source

Define how the XML data is provided to PeopleTools.

Report Definition Definition

PSXPRPTDEFN

Reporting Tools, XML Associate the XML data Publisher, Report Definition source to the report template. Reporting Tools, XML Associate the template to Publisher, Report Definition the report name. Multiple templates can be associated Select the Template tab. with one report. Select the format types that Reporting Tools, XML Publisher, Report Definition are presented when the user runs the report. Select the Output tab. Reporting Tools, XML Define the users who can Publisher, Report Definition view web-posted output in the Report Manager Select the Security tab. repository.

Report Definition Template

PSXPRPTTMPL

Report Definition - Output

PSXPRPTOUT

Report Definition - Security PSXPRPTSEC

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

487

Understanding XML Publisher Invoices

Chapter 17

Page Name

Definition Name

Navigation

Usage

Report Definition - Bursting PSXPRPTBURST

Define report bursting Reporting Tools, XML Publisher, Report Definition parameters, which allows the report output to be split Select the Bursting tab. into separate files based on a field in the XML file. For example, if you want a separate output file created for each invoice, then you can burst by invoice number. PeopleSoft delivers the burst value (BURST_VAL) field already populated in the XML file that can be used for bursting by invoice.

Creating a New Data Source

Access the Data Source page (Reporting Tools, XML Publisher, Data Source). Create a new data source if you want to use a different source for building your XML data file than the data source that is delivered. For example, if you want to generate your XML data by using a RowSet instead of an XML file. To do this will require customizations to the delivered batch programs. See Also Enterprise PeopleTools 8.50 PeopleBook: XML Publisher for PeopleSoft Enterprise, "Data Source"

Creating or Modifying a Template

Create new templates, or modify the delivered templates, by using standard desktop applications such as Microsoft Word, Microsoft Excel, or Adobe Acrobat. Oracles XML Publisher Template Builder can be downloaded to assist you in creating and modifying templates. In addition, the delivered sample XML data file can be downloaded from the Data Source to assist in building and testing your templates. The template builder plug-in can be downloaded from within the PeopleSoft application by navigating to Reporting Tools, XML Publisher, Setup, Design Helper. See Also Enterprise PeopleTools 8.50 PeopleBook: XML Publisher for PeopleSoft Enterprise

488

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

Chapter 17

Understanding XML Publisher Invoices

Uploading a New Template in PeopleSoft

After creating a new template, use the Report Definition component to upload the template. You can create a new report definition and upload your template, or you can use the delivered report definitions. If you use the delivered report definitions, use the Report Definition - Template page to indicate that the new template is the default template. If you create a new report definition, then you must create a new Application Engine program to produce your invoices in batch. The Application Engine program must have the same name as the report definition. If you use the delivered report definition, then there is no need to create a new Application Engine program. See Chapter 17, "Understanding XML Publisher Invoices," Creating a New Application Engine Shell Program, page 492. See Also Enterprise PeopleTools 8.50 PeopleBook: XML Publisher for PeopleSoft Enterprise

Creating or Modifying a File Layout

Two file layouts are delivered: BI_EXTRCT and BI_EXTRCT_CONS. These file layouts determine what invoice data is included in the XML file. The file layouts are based on the Extract tables that are used for printing invoices. The Extract tables consist of many tables and many fields. The file layout includes a subset of these tables and fields. If the file layout does not include fields that needs to be printed on your invoice, then you can create a new file layout or modify a delivered file layout. To modify a file layout: 1. Use Application Designer to view the file layout 2. Add or remove tables or fields. To add additional records, they must be added in the appropriate hierarchical order, which is demonstrated in this table: Adding Records in Hierarchical Order When adding records to a file layout, they should be added in this hierarchical order. For example, when adding records to BI_EXTRCT, they should be added in this order:
Level 0 Level 1 Level 2 Level 3

BI_EXTRCT BI_EXT_HRD_NOTE BI_EXT_SHIP_TO

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

489

Understanding XML Publisher Invoices

Chapter 17

Level 0

Level 1

Level 2

Level 3

BI_EXT_INST_SEC BI_EXT_INST_SUM BI_EXTRCT_PAY BI_EXT_SUM_GPHR BI_EXT_SUM_NT BI_EXT_SUM_IVC BI_EXT_SUM_LNNT BI_EXTRCT_LINE BI_EXTRCT_PROJ BI_EXTRCT_CONTR BI_EXTRCT_UTL BI_EXTRCT_TAX BI_EXTRCT_TXDTL BI_EXTRCT_VAT BI_EXT_LIN_NOTE BI_EXT_EXSDTL

When adding records to BI_EXT_CONS, they should be added in this order:

Level 0 Level 1 Level 2 Level 3 Level 4

BI_EXT_CONS_VW BI_EXTRCT BI_EXT_HRD_NOT E BI_EXT_SHIP_TO BI_EXT_INST_SEC BI_EXT_INST_SUM

490

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

Chapter 17

Understanding XML Publisher Invoices

Level 0

Level 1

Level 2

Level 3

Level 4

BI_EXTRCT_PAY BI_EXT_SUM_GPH R BI_EXT_SUM_NT BI_EXT_SUM_IVC BI_EXT_SUM_LNN T BI_EXTRCT_LINE BI_EXTRCT_PROJ BI_EXTRCT_CONT R BI_EXTRCT_UTL BI_EXTRCT_TAX BI_EXTRCT_TXDT L BI_EXTRCT_VAT BI_EXT_LIN_NOTE BI_EXT_EXSDTL

Creating a New File Layout To create a new file layout, the file layout must be referenced in the Application Engine program: Section BI_PRNXPN01.Init.InitVar.PeopleCode for non-consolidated Section BI_PRNXPC01.Init.InitVar.PeopleCode for consolidated. The code is similar to:
/* Initialize Variables for the Report */ BI_XMLP_AET.FLDDEFNNAME = "BI_EXTRCT"; /* File Layout Name */ BI_XMLP_AET.CONSOLIATED = "N"; /* Non-consolidated */ BI_XMLP_AET.REPORT_DEFN_ID = "BI_PRNXPN01"; /* XMLP Report Definition - must be same name as AE program*/ BI_XMLP_AET.TMPLDEFN_ID = " "; /* Report Template - Blank means use default template */

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.

491

Understanding XML Publisher Invoices

Chapter 17

Note. The first line of the code specifies the file layout to use. If Date Type fields are added to the file layout, ensure that the format specified in the file layout is in canonical format (YYYY-MM-DD). This ensures that the date format is translatable for all locales. Note. The information here must be changed to operate in your customized environment and on your particular database platform. You may also be required to amend these guidelines based on business rules and procedures in your organization. Ensure to thoroughly test these changes in your own test environment before using on your live data.

Creating a New Application Engine Shell Program

You should be able to use the delivered Application Engine programs, such as BI_PRNXPN01 and BI_PRNXPC01. However, if you created a new report definition, then you must create a new Application Engine program. This is necessary because both the report definition and the Application Engine program must have the same name. To create a new Application Engine program. 1. Select one of the delivered Application Engine programs (BI_PRNXPN01 or BI_PRNXPC01). 2. Select 'Save As', and enter the same name as the report definition that you created. 3. Modify only the initializations performed in the Init.InitVar.PeopleCode section. The code is similar to:
/* Initialize Variables for the Report */ BI_XMLP_AET.FLDDEFNNAME = "BI_EXTRCT"; /* File Layout Name */ BI_XMLP_AET.CONSOLIATED = "N"; /* Non-consolidated */ BI_XMLP_AET.REPORT_DEFN_ID = "BI_PRNXPN01"; /* XMLP Report Definition - must be same name as AE program*/ BI_XMLP_AET.TMPLDEFN_ID = " "; /* Report Template - Blank means use default template */

Note. The line of the code that specifies the name of the Report Definition is the line that needs to be changed to reference the new Report Definition. Note. The information here must be changed to operate in your customized environment and on your particular database platform. You may also need to amend these guidelines based on business rules and procedures in your organization. Be sure to thoroughly test these changes in your own test environment before using on your live data. A new Application Engine program must be defined in the PeopleTools, Process Scheduler, Processes component. It must be defined with a Process Type of XML Publisher, not Application Engine, and the Process name must be same name as the Application Engine program. Note. The Billing Extract program (BI_IVCEXT) must run successfully before the XML Publisher invoice batch print programs run. Therefore, if you add the XML Publisher processes to a new or an existing job, you must include the BI_IVCEXT process in the job and sequence it before the XML Publisher Invoice program.

492

Copyright 1992, 2009, Oracle and/or its affiliates. All Rights Reserved.