Using Custom XML with Oracle US & Canadian Payroll Reports

An Oracle E-Business Suite Technical Brief

July 2013
 Using custom XML with Oracle US & Canadian Payroll Reports

Copyright © 2013, Oracle. All rights reserved.

This document was prepared to assist the customer in the use of Oracle HRMS. Its contents may not be used for any
other purpose without written permission. The material contained herein is supplied without representation or
warranty of any kind including any implied warranties or merchantability. Oracle Corporation assumes no
responsibility and shall have no liability of any kind from the supply or use of this document and the material it
contains.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the
information herein; these changes will be incorporated in new editions of the publication.

These are licensed materials for internal and customer use only, all rights reserved, including the right to photocopy,
reproduce, translate, or make other reproductions of this document or any part thereof.

All other products or company names are used for identification purposes only, and may be trademarks of their
respective owners.

Page 2
 Using custom XML with Oracle US & Canadian Payroll Reports

Contents

Overview...................................................................................................................................................................... 4
Action Information Category ............................................................................................................................ 4
Document Type................................................................................................................................................. 6

Process Flow ................................................................................................................................................................ 6

1. Creating the custom XML code: ....................................................................................................................... 6
2. Assigning the custom procedure to the corresponding lookup value: ............................................................. 11
3. Creating the custom template with the required XML tags: ............................................................................ 13
4. Register the Custom Template with the Corresponding Payroll Report: ........................................................ 15
5. Run the Report Using the Custom Template: ................................................................................................. 19

Sample Outputs ......................................................................................................................................................... 20

Debugging .................................................................................................................................................................. 23

Appendix.................................................................................................................................................................... 24

Page 3
 Using custom XML with Oracle US & Canadian Payroll Reports

Overview
Newer processes like Check/Cheque Writer (XML), Third Party Check/Cheque Writer (XML),
Deposit Advice (XML) and PDF Payslip for the US & Canadian Payroll localizations are
generated through the BI Publisher interface. The BI Publisher engine accepts an XML file along
with an RTF template as input parameters and produces a PDF document as output.

A majority of the data elements that may be required in the report/process are part of the generated
XML file. Further, customers can customize the seeded RTF templates to get the desired look-
and-feel of the report output. However, customers also require the ability to add additional or
custom data to these XML based reports in order to print data elements that are not delivered by
the product. This document focuses on how such customization of these US and Canadian Payroll
XML based reports can be achieved. This functionality is available in Release 12.1 HRMS
Release Update Pack (RUP) 6 and later, except for use with the PDF Payslip which was delivered
previously with Release 12.1.3.

First, it is important to understand Pay Action Information Categories that the Payroll Archive
uses to store the data as well as the Document Types that are associated with the aforementioned
US and Canadian XML based Payroll reports.

Action Information Category

The Payroll Archive process gathers all relevant information from various sources and archives it
in the table PAY_ACTION_INFORMATION. This information is grouped under the following
Action Information Categories:
1. ADDRESS DETAILS
2. EMPLOYEE OTHER INFORMATION
3. EMPLOYEE DETAILS
4. AC EARNINGS
5. AC DEDUCTIONS
6. AC SUMMARY CURRENT
7. AC SUMMARY YTD
8. EMPLOYEE ACCRUALS
9. EMPLOYEE NET PAY DISTRIBUTION
10. US THIRD PARTY CHECKS
11. CA THIRD PARTY CHEQUES
12. US WITHHOLDINGS
13. US CITY
14. US FEDERAL
15. US STATE
16. US STATE2

Page 4
Using custom XML with Oracle US & Canadian Payroll Reports

Page 5
 Using custom XML with Oracle US & Canadian Payroll Reports

Document Type

Each report/process is classified with a document type name. The following table provides a list of
reports along with its document type.
REPORT DOCUMENT TYPE
Check Writer (XML)
ARCHIVE_CHEQUE_WRITER
Canadian Cheque Writer (XML)
Third Party Check Writer (XML)
THIRD_PARTY_CHEQUE_WRITER
Canadian Third Party Cheque Writer (XML)
Deposit Advice (XML)
Canadian Deposit Advice (XML) PAYSLIP
Payslip for both US and CA

Note: The PDF Payslip follows a different approach to add custom XML code unlike the other
reports. This will be explained later in the document.

Process Flow

The XML file is structured as a hierarchy of tags, which will hold data to be displayed on the
report output. The logic for retrieving additional data elements into XML needs to be defined by
the customer as mentioned below. Customizing the report involves the following steps:
 Creating the custom XML code
 Assigning the custom procedure to the corresponding lookup value
 Creating the custom template with the required XML tags
 Registering the custom template with the corresponding payroll report
 Running the report using the custom template

1. Creating the custom XML code:

The custom code should be written in a package procedure with the following input parameters, in
the same order, to fetch the additional data elements required for the report:
i. Action Context ID
ii. Action Information Category
iii. Document Type

Adding a new data element, ‘Consolidation Set’, to the Check Writer (XML) process is being
provided as an example throughout this document in order to explain the steps required to
customize the report or process.

Page 6
 Using custom XML with Oracle US & Canadian Payroll Reports

The addition of this custom data (Consolidation Set) to the Check Writer (XML) report is written
in a new package PAY_CUSTOM_XML_RULES as shown below.

The procedure CUSTOM_XML has the code to fetch the Consolidation Set information and insert
it into the XML file. Let’s say the Consolidation Set needs to be added under Action Information
Category ‘Employee Details’.

Create the package body PAY_CUSTOM_XML_RULES as shown below and make sure the
newly created package compiles successfully. It is also recommended that you follow general
PL/SQL coding standards for your custom code. To disable this custom code, please refer to the
Debugging section.

Page 7
Using custom XML with Oracle US & Canadian Payroll Reports

Page 8
 Using custom XML with Oracle US & Canadian Payroll Reports

First, filter the data based on the document type depending on which report the custom data needs
to be added to, and then filter it based on the action information category under which the custom
data needs to be added. Using the current example, since data needs to be added to the Check
Writer (XML) report output, p_document_type parameter ‘ARCHIVE_CHEQUE_WRITER’ was
used. (For other reports, use the applicable document type from the table listed in the
‘Introduction’ section). Further, to add custom data under the EMPLOYEE DETAILS
p_action_information_category, parameter ‘EMPLOYEE DETAILS’ is used. (For other
categories, use the applicable p_action_information_category as required).

For Third Party Check Writer (XML), the only valid context is ‘US THIRD PARTY CHECKS’.
For Canadian Third Party Cheque Writer (XML) the only valid context is ‘CA THIRD PARTY
CHEQUES’. Using corresponding document types and action information categories the same
package can also be used to add custom data to other reports.

Note: Take care if using the under-score character and/or caps while using the action information
category and document type.

Page 9
 Using custom XML with Oracle US & Canadian Payroll Reports

This is the simple flow diagram of XML based reports: -

Payroll Archiver

Identify eligible archived records

Obtain XML tag names from

Action Information DF

Generate XML Data

Legislation Specific XML

data

Custom XML Data

More Yes
archived
contexts

No

XML

Merge With RTF

Template

PDF output

Page 10
 Using custom XML with Oracle US & Canadian Payroll Reports

2. Assigning the custom procedure to the corresponding lookup value:

The custom procedure written in part 1 need to be defined in the lookup type
PAY_CUSTOM_XML_CODE in order to be available during processing. The reports and their
corresponding lookup codes are listed below.

REPORT LOOKUP CODE

Check Writer (XML) US_ARCHIVE_CHECK_XML
Canadian Cheque Writer (XML) CA_ARCHIVE_CHEQUE
Third Party Check Writer (XML) US_THIRD_PARTY_CHECK_XML
Canadian Third Party Cheque Writer (XML) CA_THIRD_PARTY_CHEQUE
Deposit Advice (XML) US_DEPOSIT_ADVICE_XML
Canadian Deposit Advice (XML) CA_DEPOSIT_ADVICE_XML

To assign your custom procedure to the appropriate report’s lookup code in

PAY_CUSTOM_XML_CODE lookup type, use the following steps:
a. Switch to the Application Developer responsibility.
b. Navigate to Application  Lookups  Common
c. Search for lookup type PAY_CUSTOM_XML_CODE and enter the custom procedure
defined in part 1 in the format <package_name>.<procedure_name> under Description
for the corresponding lookup code and save.

Note: For the PDF payslip, the custom procedure in the format
<package_name>.<procedure_name>, needs to be defined in SelfService Preferences under the
Business Group Classification as follows:
a. Switch to the US Super HRMS Manager (or equivalent custom) responsibility.
b. Go to Work Structures  Organization  Description.
c. Query your Business Group.
d. Under Business Group Classification, select SelfService Preference.
e. Define the custom procedure in the field ‘XML Code’ (using the format
<package_name>.<procedure.name>).

See the Appendix for more information regarding the PDF payslip.

Page 11
 Using custom XML with Oracle US & Canadian Payroll Reports

Again, using current example, since custom data needs to be added to the Check Writer (XML)
report, the custom procedure pay_custom_xml_rules.custom_xml is added to the lookup code
US_ARCHIVE_CHECK_XML as shown below.

Page 12
 Using custom XML with Oracle US & Canadian Payroll Reports

3. Creating the custom template with the required XML tags:

The BI Publisher Builder Add On can be used to edit/create an RTF template with the required
tags. Download a copy of the seeded template, make the required changes and save it as a custom
template. (Be sure not to update the seeded template definition directly.)
Here in our example, since custom data is added under the tag
CUSTOM_CONSOLIDATION_DATA, the template needs to be modified as follows:

Before change – Seeded template:

Page 13
 Using custom XML with Oracle US & Canadian Payroll Reports

After Change – Custom Template:

In the above sample custom RTF template, Employee Number has been replaced with
Consolidation Set. Since custom data is available with the tag CONSOLIDATION_SET, which is
under CUSTOM_CONSOLIDATION_DATA (at same level as Employee Number), the tag
<?EMPLOYEE_NUMBER?> is replaced with tag
<?CUSTOM_CONSOLIDATION_DATA/CONSOLIDATION_SET?>

Note: 1. Be cautious about the XML levels while creating the custom template.
2. Before using this template a sample PDF can be previewed using the BI Publisher
Builder by loading sample XML data.

Page 14
 Using custom XML with Oracle US & Canadian Payroll Reports

4. Register the Custom Template with the Corresponding Payroll Report:

In order to register the template, it is necessary to know the concurrent program short names and
data definition for each report. The following table provides the necessary information for each
report.

CONCURRENT
REPORT PROGRAM DATA DEFINITION
SHORT NAME
Check Writer (XML) PAYARCHCHQW Check Writer XML
Canadian Cheque Writer (XML) PAYCAARCHCHQW Canadian Cheque Writer XML
Third Party Check Writer (XML) PAYUSTPCHQW Third Party Check Writer XML
Canadian Third Party Cheque Canadian Third Party Cheque
PAYCATPCHQW
Writer (XML) Writer XML
Deposit Advice (XML) PYUSDEPADVXML Deposit Advice XML
Canadian Deposit Advice (XML) PYCADEPADVXML Deposit Advice XML for CA
Payslip for US US Payslip Data Definition
Payslip for CA Canada Payslip Data Definition

In order to find the seeded data definition for each report (other than the PDF payslip), perform
the following:
a. Switch to the XML Publisher Administrator responsibility.
b. Click on Data Definition.
c. Input the concurrent program short name in the Code field.
d. Click Go.

Step 1: Create a new template definition:

a. Switch to the XML Publisher Administrator responsibility.
b. Navigate to Templates  Create Template.
c. Populate the following fields:
i. Name: Enter an appropriate name (less than 50 Characters).
e.g. “Custom Template for Check Writer”.
ii. Code: Enter the code such as ‘%_PDF’ in all caps to indicate that
this template will be used for generating the PDF file. This
format is mandatory.
e.g. CUSUSCHKWVXML_PDF
iii. Application: Select ‘Payroll’.
iv. Data Definition: Select the applicable Data Definition corresponding to your
report as referenced above.
v. Type: Select RTF.
vi. Start Date: Enter a date prior to today’s date.

Page 15
 Using custom XML with Oracle US & Canadian Payroll Reports

vii. Sub template: Select ‘No’.

viii. Default Output Type: Select ‘PDF’.
ix. Description: Enter any description of your choice (less than 50 Characters).
x. File: Browse to select the desired template file created in Part 3.
Make sure to rename this file to match the template code
before selecting it. eg. CUSUSCHKWVXML_en.rtf
xi. Language: Select ‘English’.
xii. Territory: Select the applicable legislation: either ‘Canada’ or ‘United
States’.
xiii. Translatable: If applicable, check the check box (i.e. this would usually be
checked for Canada and left unchecked for the United States).
xiv. Click on Apply to save your changes.

Sample Template Definition:

Step 2: Group the Related Templates:

The templates created in Step 1 now need to be grouped so that they are available for selection
when registering it with the corresponding concurrent program.
a. Switch to the Application Developer responsibility.
b. Navigate to Application  Lookups  Common
c. Enter the following fields to create the lookup group:
i. Type: Enter an appropriate name. The name should be in the format
%<legislation code>%<concurrent program short name>%.
This format is mandatory.
e.g. VISION_US_PAYARCHCHQW_CUST
Page 16
 Using custom XML with Oracle US & Canadian Payroll Reports

ii. Meaning: Enter an appropriate name (less than 50 characters). This

name will be used for displaying the Template Groups
available for selection when registering the template.
e.g. Custom Template for Check Writer (XML)
iii. Application: Select ‘Payroll’
iv. Code: Enter the template code used in Step 1
e.g. CUSUSCHKWVXML_PDF
v. Meaning: Enter the same template code.
vi. Description: Optionally enter mandatory description
vii. From: Enter a date prior to today’s date.
viii. Save the record.

Sample lookup:

Step 3: Register the new template with the corresponding report:

Once the template grouping is complete, the custom template needs to be registered with the
applicable concurrent program so that it is available for selection when submitting the report.

a. Switch to the Super HRMS Manager/HRMS Manager/Payroll Manager (or applicable

custom) responsibility.
b. Navigate To Processes and Reports  Submit Processes and Report  Single Request
c. Run the process ‘Register BI Publisher Templates for Payroll’.
d. Enter the parameters as follows:
i. Payroll Process Name: Select the process for which the custom template
group needs to be registered. Example: Check Writer
(XML)

Page 17
 Using custom XML with Oracle US & Canadian Payroll Reports

ii. Template Group: Select the template group created in the Step 2.
Example: Custom Template for Check Writer (XML)
e. Click on OK and submit the request.

Sample submission:

Once the process has successfully completed, the custom template will be available for selection
when submitting the applicable report.

Note: For PDF Payslip, Steps 2 and 3 are not required. Once the template has been created using
the XML Publisher Administrator responsibility as mentioned in Step 1 it will then be available
for selection in SelfService Preferences. Select the custom template in SelfService Preference
under the Business Group classification as outlined below and save.

a. Go to Work Structures  Organization  Description.

b. Query your Business Group.
c. With the Business Group Classification, click on ‘Others’ and then select
‘SelfService Preference’.
d. For the Document Type ‘Payslip’, select the custom template in the ‘Template’ field
and save.

See Appendix for more information about using custom templates with PDF Payslip.

Page 18
 Using custom XML with Oracle US & Canadian Payroll Reports

5. Run the Report Using the Custom Template:

So far, a custom procedure has been written and assigned to a corresponding lookup code, and a
custom template has been created to add the additional custom data that has been fetched through
the custom procedure. This template group has been created and registered with the corresponding
concurrent program so that it is now available for selection when submitting the report.

When submitting the report, select the template group from the list of values. (For PDF Payslip,
the template that is defined in SelfService Preferences will be used.)

Multiple custom templates can be created, grouped and registered with the corresponding report
so that they can be used to display the required additional custom data.

Selecting a custom template for the Check Writer (XML) report:

Page 19
 Using custom XML with Oracle US & Canadian Payroll Reports

Sample Outputs

Snippet of the XML output from the Check Writer (XML) report using seeded report:

Page 20
 Using custom XML with Oracle US & Canadian Payroll Reports

Snippet of the XML Output using custom code:

Page 21
 Using custom XML with Oracle US & Canadian Payroll Reports

Sample of the Check Writer (XML) output using seeded XML data:

Sample of the Check Writer (XML) output using custom XML data:

Page 22
 Using custom XML with Oracle US & Canadian Payroll Reports

Debugging

1. If the custom XML code is not being used when running the report, check the profile
option 'PAY: Disable Custom XML Code (Yes/No)'. It should be set to ‘No’ or left blank
in order for the custom code to work. Please note that if any issue is encountered in any
of the processes having custom code, then Oracle Support and/or Development will
require that you run the process by setting this profile option to ‘Yes’ in order to
determine if the process works without the custom code. Please note that issues with
custom code will not be supported by Oracle Support/Development.
a. Switch to the System Administrator responsibility.
b. Navigate to Profile  System  Common
c. Search for 'PAY: Disable Custom XML Code (Yes/No)' at site level.
d. Set to Yes/No as per the requirement. (The default is ‘no’.)
2. The following query should provide the correct custom XML procedure that has been
defined for the report. If not, check the applicable value in the lookup definition form.
SELECT description
FROM fnd_lookup_values
WHERE lookup_type = 'PAY_CUSTOM_XML_CODE'
AND language = 'US'
AND lookup_code = <lookup_code corresponding to the process>

3. If the custom XML data still doesn’t appear in the xml output, check that the correct
Document Type and Action Information Category were used (also pay attention to any
underscore characters and/or caps that may be used).
4. If the custom data that is produced in the XML output is incorrect, check the
functions/cursors/logic that has been used in the custom procedure to fetch the custom
data.
5. If custom data is produced in the XML output, but not in the PDF output, check the tags
that were used, the XML levels and the template that has been picked up by the process.
The PDF output can also be previewed using the applicable custom template after
loading a sample XML file to the BI Publisher Builder add on.

Page 23
 Using custom XML with Oracle US & Canadian Payroll Reports

Appendix

Basic Setup to Generate the PDF payslip:

1. Following legislation rule needs to be present in the pay_legislation_rules table:

Column Value
LEGISLATION_CODE <Legislation Code (US/CA)>
RULE_TYPE PAYSLIP_MODE
RULE_MODE {XDO | OAF}

Absence of this rule for your legislation will result in the Oracle Applications Framework (or HTML)
based payslip being generated. If Rule Mode is set to ‘OAF’ then Oracle Applications Framework based
payslip will be generated. Usage of the custom XML code and custom XML template are applicable only
for the PDF based payslip, which is only available in Release 12.1.3 and later.
2. Configure the Self Service Preferences available at the Business Group level. It comprises the following
segments:
a. Document Type – This specifies the type of document for which the following segments will be
configured. Payslip should be chosen from the list of values attached to this segment.
b. Online – Selecting Yes/No determines whether the online payslip is viewable by employees working
under the current business group.
c. Paper – This segment does not apply to the online payslip.
d. Template – Select the custom template to be used for formatting the online PDF payslip. You need to
register the custom template in 'BI Publisher Administrator' responsibility as highlighted above in
Section 4. The data definition used for payslip is '<legislation code> Payslip Data Definition'.
Note: Only Step 1 of Section 4 applies when registering the custom template for the online PDF
payslip; steps 2 and 3 of Section 4 are not required.
e. XML Code –If you wish to append the custom data to the existing XML output, you can create an
XML generation procedure and specify it in this segment in the format of
<package_name>.<procedure_name>.
f. Effective Date – This date provides a smooth migration to the PDF Payslip for the US and Canadian
localizations from the existing Oracle Applications Framework based online payslip architecture. All
payslips prior to this date will be displayed using the OAF architecture while PDF based payslip will
be generated for payslips effective on or after this date.
g. Payslip Employer Address – Select which Employer Address should be displayed on the payslip
(options are ‘GRE Address’ or ’HR Organization’ address). By default, the HR Organization address
is displayed.
h. Display Payslip GRE Addr From – If ‘GRE address’ is selected in the previous field, the GRE address
will be shown on the payslip after this date.

Page 24
 Using custom XML with Oracle US & Canadian Payroll Reports

Note: The segments ‘Template’, ‘XML Code’ and ‘Effective Date’ are specific to PDF based payslip
(when the custom template and custom code are defined). The remaining fields are common to both
OAF and PDF (XML) based payslips.

The above PDF Payslip parameters can be overridden at Organization and Location levels. The precedence
goes to the lower level, meaning Location settings will override Organization and Business Group settings
and Organization will override Business Group settings. Defining Self Service Preferences at all three
levels is acceptable: e.g. Users may specify a custom template at Location level while specifying custom
XML Code at the Business Group level . The only constraint is that the custom template and effective date
must be specified in Self Service Preferences for at least one of the levels. Non-compliance of this
constraint will result in generation of the OAF payslip and not the PDF payslip.

3. After completing the above configuration, the custom payslip is now ready for viewing through Self
Service. The Online payslip is available through the Payslip function under the Employee Self-Service
responsibility. The Payslip from the most recent pay period is automatically displayed after clicking the
Payslip function. Users can choose other pay periods from the drop-down list available under the Choose
Payslip region.

The following matrix shows the application behaviour with respect to Template and Effective Date segments.

Template Field Effective Date Field Application Behaviour

Blank Blank OAF Payslip is generated

Entered Date Greater than system date OAF payslip is generated

Entered Date Less than or equal to system date PDF payslip is generated

Page 25
 Using custom XML with Oracle US & Canadian Payroll Reports

Blank Date (any date) OAF Payslip is generated

Entered Blank PDF payslip is generated

Important Note: Custom template and custom code are applicable only to the PDF payslip.

Page 26
 Using custom XML with Oracle US & Canadian Payroll Reports

Using custom XML with Oracle US & Canadian Payroll Reports

July 2013
Author: Oracle EBS HCM Product Development

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065

U.S.A.
Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
www.oracle.com

Oracle Corporation provides the software

that powers the Internet.

Oracle is a registered trademark of Oracle Corporation. Various

product and service names referenced herein may be trademarks
of Oracle Corporation. All other product and service names
mentioned may be trademarks of their respective owners.

Copyright © 2002 Oracle Corporation

All rights reserved.

Page 27