HCM Extracts Approach and Troubleshooting Guide

An Oracle Whitepaper
May 2014
HCM Extracts: Step-by-Step Approach and

Troubleshooting Guide
HCM Extracts: Step-by-Step Approach and Troubleshooting Guide
Disclaimer
The following is intended to outline our general product direction. It is intended for information purposes
only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code,
or functionality, and should not be relied upon in making purchasing decisions. The development, release,
and timing of any features or functionality described for Oracle’s products remains at the sole discretion
of Oracle.
Fusion HCM Extracts: Step-by-Step Approach and

Troubleshooting Guide
Document Control
Date Author Version Change Reference
08-Apr-2014 Shesha Shila Bharadwaj R 0.1 First Release

16-Apr-2014 Rajesh Jupudi 0.2 Revised
25-Apr-2014 Rajesh Jupudi 0.3 Incorporated feedback received during Review
01-May-2014 Rajesh Jupudi 0.4 Incorporated feedback received from Alison
(Except numbering)
08-May-2014 Rajesh Jupudi 0.4 Incorporated feedback received from Alison
(Including the new hierarchy numbering)
20-May-2014 Rajesh Jupudi 0.5 Incorporated feedback received from Bharadwaj
(Including the new hierarchy numbering) & Alison’s
comments sent by email
Audience
This document contains a robust step-by-step approach to creating a HCM Extract. This guide
helps in finding issues at the exact step that introduces it and ensures better results.
This document contains troubleshooting steps that enable support teams and customers to
debug issues with their HCM Extract setup. Basing our interactions and review of the bugs
received, we aim to update this document on a regular basis. Please refer to the latest
document at the location.
Prerequisites: HCM Extracts User Guide, Delivery Options Guide, and BI Publisher Guide for
creating templates. Please read the documents including FAQs.
The guide is applicable for Release 7 PB7 onwards.
Note: Terminology from Release 8 is modified to refer to Blocks as Data Groups, Data
Elements as Attributes, Links as Connections, and Block Criteria as Filter Criteria.
2|Page
Documentation links on MOS
Note Details
1429892.1 Defining a Simple HR Outbound Interface Using HCM Extracts
- Glossary of terms like Database Item, Data Base Item Group,
User entity, Contexts
- Overview of the Extract definition, Parameters, Blocks, Block
Links, Block Filters, Elements
- Designing the Extract Structure
- Creating an Extract Definition
- Submitting an Extract
1559127.1 Oracle Fusion HCM Extracts Guide Release 5
- HCM Extracts User guide
- Release 7 Entity Attributes
- Extracts presentation (ppt)
1573099.1 Oracle Fusion HCM Extracts: Delivery Options
1536245.1 How to Enable Logging for Oracle Fusion Global Payroll
1559161.1 Oracle Fusion HCM Extracts FAQs for Release 5
1504483.1 All White Papers for Fusion Applications HCM
1565118.1 Database Items for Extracts and Formulas in Oracle Fusion HCM
1327881.1 Fusion Applications Technology: Master Note on Business Intelligence
and Reporting
1340506.1 Important Documentation for Business Intelligence and Reporting,
contains troubleshooting documentation, all the guides for BI publisher.
1595283.1 Oracle Fusion Human Capital Management File-Based Loader for
Release 7. This document contains good information about setting up
the extract and viewing its results.
Refer to the following WebEx recordings on HCM extract setup and delivery options:
 Day 1
 Day 2
3|Page
Table of Contents
1 Introduction ......................................................................................................................... 6
2 A step-by-step approach to create an HCM Extract ............................................................ 6
2.1 Design the Extract Structure ........................................................................................ 6
2.2 Define the Extract ........................................................................................................ 8
2.3 Submit an Extract without Delivery Options.................................................................. 9
2.4 Create an empty BI Publisher Report ........................................................................... 9
2.5 Create BIP Template and Test ....................................................................................10
2.6 Add Layout to BI Report and Test ...............................................................................10
2.7 Preview Extract Output in BIP .....................................................................................12
2.8 Schedule the Report to Check BIP Delivery Status .....................................................12
2.9 Configure Delivery Options .........................................................................................16
2.10 Submit an Extract........................................................................................................18
3 Troubleshooting Steps .......................................................................................................19
3.1 Known Issues .............................................................................................................19
3.2 Issues with Importing Extract Definitions .....................................................................19
3.3 Flexfield DBIs are not Visible ......................................................................................20
3.4 Extract Run Errors ......................................................................................................20
3.5 Extract without Delivery Options Errors When Run .....................................................20
3.6 Extract Runs to Success, but XML Output is empty ....................................................22
3.7 Successful Extract with Partial XML Output ................................................................22
3.8 Successful Extract with Duplicate Rows in XML ..........................................................23
3.9 Successful Extract with XML not Visible in View Results.............................................23
3.10 Extract runs into error after attaching Delivery Option .................................................24
3.11 Other issues................................................................................................................27

4|Page
4 What if you still face an issue? ...........................................................................................29
4.1 Extract Definition File ..................................................................................................29
4.2 Provide us the E-Text or RTF template .......................................................................29
4.3 Enable GMFZT logging ...............................................................................................29
4.4 Provide us the ESS error logs .....................................................................................30
4.5 Provide us the BI logs .................................................................................................31
4.6 Advanced Debug logs (This is for Oracle Support Reference only) .............................31
4.7 Checklist .....................................................................................................................32
Appendix ...................................................................................................................................33
5|Page
1 Introduction
HCM Extracts is a volumetric data extraction tool that you can use for complex extraction and
reporting needs. It can extract information from Fusion HCM and deliver to third party
destination in the required format.
When you run an extract, the application archives the data and generates the output in an XML
format. Based upon the setup in delivery options, this XML output is then passed on to BI
Publisher and gets transformed into formatted output (HTML, PDF, EFT, or XLS) and delivered
(through email, fax, ftp, or print).
2 A Step-by-Step Approach to Create an HCM Extract

Follow this approach to avoid running into failures and to help identify issues. It is recommended
that you perform the following steps in a sequence.
2.1 Design the Extract Structure

In this primary step you need to identify the user entities (UEs), DBIs, criteria and connections
required between UEs. You need to start by identifying the UEs, DBIs, and then work out a
hierarchy linkage among them. When the requirement is to retrieve single row information, in
most cases you will not need separate UEs.
Sample use case for designing an extract structure: ‘Extract all departments with name and
location details; for each department, extract all employees with their full name, primary email-
address, phone and visa details’
1. Identify the data that will have multi-row information (plurals). In this case, they are
departments, employees, phones and visa which would act as main logical entities.
2. Identify the UEs that hold the above details (in the User Entity lookup available in HCM
Extracts Block Definition Page or through the HCM Data Objects tree available from
Rel8 onwards)
3. For Department, which is stored in Fusion as an ‘Organization’ with classification code
as ‘DEPARTMENT’, we need to create a root block (Departments) with UE as
‘PER_EXT_SEC_ORGANIZATION_UE’, and block criteria as Classification Code =
‘DEPARTMENT’
4. For Employees, create a block (Employees) with UE as
‘PER_EXT_PAY_EMPLOYEE_UE’, and create other blocks for Phones (UE:
PER_EXT_PHONES_UE), and Visas (UE: PER_EXT_VISA_PERMITS_UE)
5. Now that the blocks are created, lets create connections with appropriate DBI mappings,
as below:
 Departments ~ Employees (Using Organization Id DBI)
 Employees ~ Phones (Using Person Id DBI)
 Employees ~ Visas (Using Person Id DBI)
6|Page
Departments has one child block which is employees; while Employees has two child
blocks: Phones and Visas.
6. Now we need to identify the number of records needed to logically group the attributes
inside each block.
a) Departments block requires a record with ‘Next Block’ defined as Employees. This
record would contain department name and department location attributes.
b) Employees block requires a record that contains Full Name, E-mail Address details.
c) Phones and Visas blocks require records for the data they contain.
d) Since Employees block has two child blocks (siblings), we will need hierarchy
traversal records defined for each child block (sibling). So two hierarchy traversal
records are required each with the next block indicated as ‘Phones’ and ‘Visas’
respectively.
When you create a child block you must perform the following steps:
 Link the parent and child blocks by defining a block link

 Identify the record level at which the child block processing occurs
 Set the ‘Next Block’ value to that of the child block in the record definition of
parent block
So for the above case, where there are two hierarchy traversal records existing, you
need to set Phones, Contacts as the Next Block in each of them.
Frequently used UEs:
User Entity Purpose Comments
PER_EXT_SEC_ORGANI Used to retrieve organizations You need to explicitly filter

ZATIONS_UE (such as departments, legal specific organization by the
employers, business units) classification code such as
‘DEPARTMENT’,
‘HCM_LEMP’,
‘FUN_BUSINESS_UNIT’.
PER_EXT_SEC_PERSON Used to retrieve all the Person

S_UE related information.
PER_EXT_SEC_ASSIGN Used to retrieve all the Person,

MENT_UE Assignment, Salary related
information
7|Page
PER_EXT_PAY_EMPLOY Used to retrieve all the Person,

EES_UE Assignment, Salary, Payroll
(Payroll, Element Entries)
information.
PER_EXT_SEC_POSITIO Used to retrieve Position, Jobs

NS_UE and Grade Work Structure details
PER_EXT_SEC_JOBS_U
E
PER_EXT_SEC_GRADES
_UE
PER_EXT_RESET_UE It’s a dummy container used to It’s also used to reset

organize sections at root level, effective date when you
when you need more than one of use historical UE.
above UEs as child blocks
(siblings). Use this only when you are
an expert user of HCM
Extracts. Otherwise seek
suggestion or consent from
development.
PER_EXT_SEC_ASSIGN Used to retrieve historical

MENT_RANGE_UE assignment related information
Typically the above UEs should be used in root block. Use other UEs only when you are an
expert user of HCM Extracts and are clear on the requirements and expected behavior. You can
log a SR or a forum question on development to get assistance or confirmation in this regard.
Frequently used child UEs are: National Identifier (NID), Phones, Passport, Manager, Element
Entries/Range, Salary/Range, and Addresses You use these at child block level only. If you use
them as the root block, then data would not be extracted.
Sometimes you will need to create a child block and use multi row UEs for cases where there is
no single row DBI delivered. For example: we have single row DBI to return the primary email
address or primary NID. If you require other information such as secondary email or other NID,
you have to create a child block and filter appropriately.
2.2 Define the Extract

Navigation: Go to ‘Navigator: Data Exchange > Manage HCM Extract Definitions’
1. Create the extract as per the design above.
8|Page
2. Check the validity of the extract in Execution Tree and make sure that the extract setup
is valid
3. Generate / Compile All Formula, and verify that Formulas are generated and compiled
(you will see a tick mark next to the formula).
4. Click on ‘Export XML Schema’ and download the file to local desktop. You need to use
this file to create the BI Publisher report / template.
Do not define the delivery options now.
2.3 Submit an Extract without Delivery Options

Navigation: Go to ‘Navigator: Checklists > Submit a Process or Report’
1. Choose the Extract and run it by providing the flow instance name and parameters.
2. Process should complete successfully. If not, check for the fast formula compilation
status, block filter criteria, data elements definition status.
Proceed to the next steps only when the extract run is successful.
3. Copy the flow instance name for future use.
Note: There are two known issues when you submit extract in the Data Exchange WA. 1. You
cannot view the output in View Results 2. You can run the extract only once after your login.
Hence it is recommended that you use the Checklists WA for submitting the extract and viewing
the results.
2.4 Create an empty BI Publisher Report

Navigation: Go to ‘Navigator: Reports and Tools’
1. Create a BIP report using existing standard Global Reports Data Model
Path: /Human Capital Management/Payroll/Data Models/globalReportsDataModel
The above data model is standard and should be used for all HCM Extracts based
reports unless otherwise specified.
The BIP report created above is empty and does not have a template within it.
2. Save the report in ‘Custom’ catalog folder or any child folder within it.
3. Click on ‘View Report’ and provide the flow instance name (from step 2.3).
4. Verify that the XML output displayed is the expected data from your defined extract
hierarchy.
Note: You can download/export the XML to your local machine for testing the template you will
create in next step. If you get an empty XML, follow the diagnostic steps in next section and fix
the problem.
Refrain from modifying the globalReportsDataModel.
9|Page
2.5 Create BIP Template and Test

Prerequisite: Local MS Word with BI Plug-in.
1. Use BI Plug-in for MS Word to create required template as per your requirement.
2. You can refer to BI Guide which is included with the installation to create template to get
the report in required format.
For example, you can create a RTF template to generate PDF/DOC/HTML formats and
create an E-Text template to create CSV/TXT/Fixed and Delimited output formats.
3. Use the Template Viewer (included with the BIP installation) to test the RTF/E-Text
template you created.
4. Load the XML (downloaded in step 2.4 above) and choose the template you created in
this step and verify that the PDF/TXT output is generated as you expect.
Sample Screenshot of the Template Viewer
2.6 Add Layout to BI Report and Test

1. Open the BI report created in step 2.4 and import the layout created in step 2.5.
10 | P a g e
2. Click on the ‘Upload’ icon under ‘Upload or Generate Layout’ and complete the following
information:
Parameters Details
Layout Name Free text to identify the underlying report layout.
Note: Use the layout name to configure the Template (Layout) name
within delivery options.
Template File File name of the RTF/ EFT template saved on the local machine -
should be selected from the browse option
Note: This filename should not be considered while configuring

delivery options.
Type Select from the LoV – You should choose RTF template or eText
template based on the template you created.
Locale Select from the LoV
3. Save the report.
11 | P a g e
2.7 Preview Extract Output in BIP

Navigation: Click on Open Report > View Report.
1. Enter the flow instance name (from step 2.3) to view the output in required format.
2. If you cannot view the output in required format or the output has a few missing
attributes then either there is an issue with the template or while uploading the template
a wrong template is chosen. Proceed further after fixing the issue.
In the below example, a BI Report was created at location “/Custom”, with the name “Taleo”.
An E-Text template was uploaded with ‘BU’ as the layout name. In ‘View Report’ the payroll
flow instance name was provided and we can see the output generated in required format.
2.8 Schedule the Report to Check BIP Delivery Status

Report is now capable of generating output in required format. If you want to deliver this report
via FTP or Email, we need to verify that the BIP environment is configured for the required
deliver types. For this you need to schedule the BI report.
a) Navigation: Select your report in the catalog and Click on ‘More > Schedule’.
12 | P a g e
b) Provide sample flow Instance name which ran successfully (from step 2.3).
Note: The value in the Report field above should be configured as the ‘Report’ in Delivery
Options.
c) Follow below steps to configure Email/SFTP
i) Click on Output tab, Un-check ‘Use Bursting Definition to Determine Output’ (if
available).
ii) Enter the layout and ‘Add Destination’ choosing an Email/SFTP destination.
13 | P a g e
14 | P a g e
iii) Submit the process.
iv) To check if Email/SFTP is successful, click on Report Edit > History and see if
process succeeded without errors.
v) If process fails, then drill down to find the root cause of the issue by reviewing the
error in the job history.
vi) Also, try running other reports that are not based on HCM Extracts, to verify whether
the issue is specific to reports using HCM Extracts or a generic issue.
If you face issue even with non HCM Extract based reports, it confirms that the issue
is with BI Server configuration, so you need to get the BI Server configuration
corrected. You may need to contact Support/ CloudOps to configure your SFTP or
Email.
vii) If non HCM Extracts reports are working fine but not the above report, please create
SR / bug with error you see in Job History.
15 | P a g e
2.9 Configure Delivery Options

Navigation: Go to ‘Navigator: Data Exchange > Manage HCM Extract Definitions’
1. Return to the extract definition and define the delivery option.

2. Define the delivery option as per the delivery requirements:
Parameters Details
Start Date Do not modify
End Date Do not modify
Delivery Option Name This is a Free Text field. You can enter an appropriate name.
For example: Email to HR
Output Type Delivery file output type i.e. PDF, CSV, XML, DOC.
The value you choose should be compatible with the

Template/Layout you provided in delivery option.
Choose Output Type as Text when the expected output

format is text or CSV or deliminated file.
Note: If the expected output format is PDF / HTML / DOC,

then RTF template should have been created in BIP. If the
expected output format is text / CSV / deliminated file, then
eText template should have been created in BIP.
Report Path of the report created in the BI Publisher
Note: Report should include the BI Folder path:

/Custom/<Your Folder>/<ReportName>.xdo. This path should
match with the directory structure of the report in the BI
Publisher setup.
If you have defined the report in ‘Shared Folder’ location, you

should not include the ‘Shared Folder’ location in the path.
(Please refer to step 2.8 for correct report name and template
to use in delivery options.)
Output Name Name of the output file. This can be based on the
requirement of consuming application. You can use wild
cards allowed by BI such as %d, %m etc
Template BI publisher report layout name.
Note: Template name can be a free text; this should be same

as what is set-up in BI Publisher.
Delivery Type Delivery Mode i.e. FTP, Email, Fax, etc.
Note: If you want to view the result in the UI, then set the
16 | P a g e
Delivery option to ‘None’.

Bursting Node Please leave this field empty for a regular extract definition.
3. Specify the additional details related to the delivery type defined in the delivery option.
For example, if FTP is selected as the delivery type, then below details such as Server Name,
Remote Directory and Remote File Name would need to be specified.
Note:
1) Server name should be the server tag name provided in BIP Administration. It should not
be the SFTP Host Name (such as sftp.oracle.com). As indicated below, the server name
to be specified is ‘fusion_ftp’ not sftp.cloud.oracle.com.
2) User needs to have the BI Administrator Role in order to have access to the
Administration link. This role has ability to see the BI Administration link and create
17 | P a g e
folders to save data models. Please refer to Note 1395598.1 (How to assign BI
Administration Role to a Fusion Application User).
3) Similarly for other delivery types such as E-mail, the ‘From' E-Mail Address, Message
Body you must specify these details in delivery option details. Separate multiple email
addresses with a comma for example: hr@xyz.com,myname@xyz.com.
If you choose E-mail as the delivery type, then the following fields are mandatory: Subject,
Email Address, and From.
2.10 Submit an Extract

Navigation: Go to ‘Navigator: Checklists > Submit a Process or Report’
1. Choose the Extract and run it by providing flow instance name, parameters and
schedule.
2. When the process completes, verify the output is delivered to destination in your specific
format and also check it in View Results.
18 | P a g e
3 Troubleshooting Steps
This section lists the common issues and the steps to identify the root cause and solve the
issue. Before contacting Development, it is recommended that you go through the following list
to identify / debug the issue.
3.1 Known Issues

a) Issue while submitting an Extract from Data Exchange WA: To submit or run an extract,
always use Payroll Checklist Work Area > Submit a Process or Report. If you use Data
Exchange WA > Submit an HCM Process (Submit Extracts), you cannot view the output nor
can run different extracts. You can run the extract only once after your login.
b) Changes made in Refine HCM Extracts cannot be exported. After the extract is imported
into the target instance, you will need to perform the same steps again (for example
lookups, recursive scheduling definitions).
c) If a new multi-row DBI (which is directly attached to user entity – ideally name starts with
Extract*) is delivered by development team, using it in old or existing extract may cause
issues. Once the patch is applied, the existing extract will not be of use (which has new DBI
delivered). You need to create an extract by copying from the existing extract, and add the
DBI.
d) Do not use Saved Search on the Manager HCM Extracts Definition page. If you use save
criteria, then extract definitions may be corrupted, so if possible don’t use Saved Search.
3.2 Issues with Importing Extract Definitions

There are pre-requisites for importing the extract definition, when you
Scenario Pre-requisite step to be performed
Fast Formula is used for block criteria or rule The fast formula needs to be created in the
based data elements. destination system (with the same name and
start date).
Data elements are based on Flexfield DBIs Generate the DBI’s by running the ‘Generate
that are generated from ‘Generate Database Database Items’ process and the same set of
Items’ process. parameters used in the source instance.
19 | P a g e
3.3 Flexfield DBIs are not Visible

DBIs for DFF’s will be available as Person Attribute Date1, Person Attribute Date2, and so on,
Person Attribute Number1, Person Attribute Number2, and so on, Person Attribute Text1,
Person Attribute Text2, and so on.
For flexfields (such as DDFs, EFFs, and KFFs) use the Generate Database Items process to
generate the UEs and DBIs with the required name and context. Run the process by providing
required flexfield name and context. UEs and DBIs would be generated starting with name as
‘FlexfieldCode_ContextCode…’. For a single row flexfield context, DBI would be readily visible
in Data Element. For a multi-row flexfield context, you need to use the generated flexfield User
Entity as child block or in fast formula as Array DBI.
Note: Do not select a Legislative Data Group (LDG) while running the Generate Database Items
process.
3.4 Extract Run Errors

When an extract errors out, you will need to reverse track in a step by step mode, to identify the
root cause of the issue.
Remove the delivery option and follow the approach steps described earlier (from step 2.3
onwards). If the extract run is successful then you know that the issue is with delivery option
configuration; if the extract run is not successful, follow next step.
3.5 Extract without Delivery Options Errors When Run

The following issues could be the reason why the extract is failing even though the delivery
option is not yet defined.
Start with verifying the run time parameters and extract definition date to verify that they are
correct.
a) Invalid Extract Definition: Go to Extract Execution Tree and verify that the extract
definition is valid.
If it is not valid and shows a message as "Extract definition Invalid", then depending on the
messages you need to fix the issue. If the message says "The root block is not linked to the
hierarchy", you need to provide the correct block link and "Next Block" field in the last record
of Parent Block.
You can refer to Note 1566913.1 Manage HCM Extract - The root block is not linked to the
hierarchy for solution.
20 | P a g e
b) Extract Record Formula Not Compiled: Verify that all the fast formulas are compiled.
Status should show a green tick mark . One or more of Extract Record formula may not
be generated or compiled or in a invalid state. Click on ‘Compile All Formula’ to generate run
time components of extracts and make sure all of them are compiled.
c) Block Criteria Syntax Error: Verify the syntax of block criteria expression. For example
if you want to filter on ‘FUN_BUSINESS_UNIT’ as the Classification Code, you need to add
the block criteria, you need to select 'PER_EXT_ORG_CLASSIFICATION_CODE’, move it
to center, select operator ‘=’ and move it to center and then add the constant
‘FUN_BUSINESS_UNIT’.
d) Invalid Fast Formula in Block Criteria: One or more formula used at block criteria
(Extract Criteria type) or Data Element (Extract Rule) is not compiled or in error. Verify that
the Fast Formula used in Extracts are in compiled status.
21 | P a g e
e) Incompatible DBI: You may have used DBIs that are known to create issues. Refer to the
Appendix for the extensive list of DBI. These DBI are for internal use (such as ‘Person Id -
Person‘) and mostly contain a ‘Person’ word and a hyphen.
f) Formula Start Date after Extract Definition Start Date: Ensure that the fast formula
start date is earlier or same as the extract definition start date.
Note: You can also use the process error log (step 4.4) to help debug the above issues.
3.6 Extract Runs to Success, but XML Output is empty

a) User Entity Filter Criteria: Verify the validity of the block criteria defined at block level.
Also, please verify that data exists that satisfies the block criteria, effective date and
parameters with which the process was run.
b) Threading DBI issues: If you want to remove the threading DBI after attaching it and are
unable to do so, then follow these steps:
 Export the extract

 Remove threading DBI references (UserName under MultiThreadActType
and MultiThreadActType) from XSD file
 Import the file to create new extract without threading.
Note: The issue is fixed and is documented here for your reference.
Example:
<Extract_Block><BaseUserEntityName>PER_EXT_PAY_EMPLOYEES_UE</BaseUserEntityName>
<BlockName>employeeblk</BlockName><XmlTagName>employee_blk</XmlTagName>
<MultiThreadActType>P</MultiThreadActType><UserName>PER_EXT_PAY_PAY_RELATIONS
HIP_ID</UserName>
Bolded & italicized text should be removed.
c) Child block is Missing / Incorrect: Verify that link exists between parent and child
blocks and is correct. For example, if you are linking Person block with Assignment block (as
child), the block link should on PERSON_ID and not any other DBI such as
BUSINESS_GROUP_ID. Also, check that the data exists in child blocks, as on the effective
date of running the extract.
3.7 Successful Extract with Partial XML Output

When the extract run is successful, but output is not complete (data is missing in some data
elements)
a) Date Range: Verify that the actual data (such as person data) is within the range of run
date.
22 | P a g e
b) Extract Record Formula Generation: Verify that the associated Fast Formula for the
data element is generated and compiled after the attribute was added. Also verify that the
Extract Record and Fast Formula are created as on Extract Definition Start Date.
c) Extract Record Formula Generated for Different Date Range: Extract Record
allows you to extract different set of data elements for different date ranges with the help of
Effective Dates. This could be a cause of formula corruption if mishandled.
When the Fast Formula session date is changed to a different value than the Extract Start
Date or Extract Record Creation date, Extract Record Formula can get generated with a
different date range. This would lead to different outputs and can be a reason for an
attribute not being extracted.
To resolve this issue, copy the Record Formula name from Extract Record page and go to
Payroll Calculation Work Area > Manage Fast Formula > Search and Select the fast
formula > Delete it. Come back to Extract Definition and generate and compile record
formula.
You can further debug exact reason by opening the record’s fast formula and reviewing the
code. The code could have comments about the reason of exclusion.
3.8 Successful Extract with Duplicate Rows in XML

a) Valid Criteria missing: Verify that a valid block criteria exists (If you don’t provide criteria
for the assignment, then assignment terms data may cause duplication, for example include
criteria as Assignment Type = ‘E’).
b) Multi threading DBI issue: When you are using the historic UEs and configure a multi-
thread DBI based on this UE, you will encounter multiple row extraction issue. Threading
DBI selected should be unique for the block. If you use a DBI that is not unique, select the
block criteria such that only one row is returned for that Block / Threading DBI.
For example: If you are using PER_EXT_SEC_PERSON_UE, make sure you add Person
type in the block criteria. Also, refer to Bug 17777850 - HCM EXTRACTS:
MULTITHREADING BLOCK RESULTS IN DUPLICATES where a solution is provided by
adding block criteria.
In some scenarios you may have to add a parent block to resolve the issue. For example if
you are using Assignment Historical User Entity in root block (Assignment Id is not unique in
this UE), it is preferred to use Person UE or Assignment UE (non historical) as parent block
and associate threading DBI to parent instead.
3.9 Successful Extract with XML not Visible in View Results

Output would be visible in View Result, only if you attach at least one valid delivery option
(such as delivery type: ‘None’).
23 | P a g e
In Delivery options provide valid Report path, Output Type as ‘Data’ and Template leave
template as blank, delivery type as ‘None’
3.10 Extract runs into error after attaching Delivery Option

a) Invalid Path and Template Name:
Review the step 2.9 described earlier. You might have provided an invalid report path or
template name in delivery options. You can verify by scheduling the report and referring to
the following fields.
You can copy the exact report path from ‘Report’ field below to avoid any typo issues. You
can also find the Layout Name by editing the BI report and copying the layout name.
Multiple times we have seen this issue to be the root cause, so we recommend you double
check the report path and template names.
24 | P a g e
Report Path:
Template Name (or Layout Name of BI):
25 | P a g e
b) Incompatible Output Types: Output types are based on the type of templates you
create. You can also quickly check possible formats allowed for a layout uploaded when you
do scheduling (step 2.8). In the below example have uploaded a RTF template and below
are the output formats compatible.
Similarly if you have uploaded E-Text template you can see only ‘Text’ output is compatible
and you can use it in Delivery options. Note: Though the expected output format is CSV or
Text or Delimited, you should configure the Delivery Option – Output Type as Text. Similarly
while configuring delivery options, when the expected output format is XML, you should
choose Output as Data.
Not all types are compatible and can be used in Delivery options for an uploaded template.
You can choose PDF or HTML or DOC if you upload a RTF template. You can choose Text
if you have uploaded E-Text template. You cannot use a PDF output type if you have
uploaded an E-Text template or you cannot use CSV or text if you have uploaded a RTF
template. Please refer to BI documentation for more details.
c) Modified Global Reports Data Model: The default data model might have been
modified or accidentally corrupted /Human Capital Management/Payroll/Data
Models/globalReportsDataModel. We have seen few customers who have copied the
globalReportsDataModel and created report on top of it. We would not suggest this path and
development team cannot support such cases unless there is some special reason
preapproved by Development.
26 | P a g e
d) Security Settings: Please check the security permission of all the report and folders in
the hierarchy where the BI Report is created. You can choose required report or folder in
right pane and click on Permissions as shown below
e) Invalid template and template type: Verify step 2.7 of the approach described earlier. If
you create a wrong template or provided a wrong template type while uploading the
template, it may cause issue. Please go to BI Report > View Report, substitute your flow
instance name and see if output is visible in required format.
f) Unable to perform SFTP or email: Verify from step 2.3 of the approach described
earlier and see if you can successfully get the output.
3.11 Other issues

a) After upgrade, Extract run fails: After an upgrade the HCM extract may fails with the
following error
Solution: Re-compile extract fast formulas going to execution tree and clicking ‘Compile All
Formula’
27 | P a g e
b) Buffer issue: If you face the following “string buffer too small” error as below, disable
GMZFT logging and run the extract.
Steps to disable GMFZT logging:
1. Navigator > Tools> Setup and Maintenance > Search for Manage Payroll Process
Configuration.
2. Goto task and click on Default Group.
3. In the configuration group details section DELETE the row ‘Logging Category Detailed
information that is used for investigating problems. Default: no logging’.
c) User Impersonation Issue: BI Log has the following ‘Fault from server :
java.lang.SecurityException: Failed to impersonate user fusion_apps_hcm_ess_appid’
Solution: Follow the steps indicated in Bug# 18550593. Indicative steps to be run by
DevOps are below:
1. Stop OBIPS (cd /u01/APPLTOP/instance/BIInstance/bin - ./opmnctl stopproc ias-

component=coreapplication_obips1)
2. cd
/u01/APPLTOP/instance/BIInstance/bifoundation/OracleBIPresentationServicesComponent
/coreapplication_obips1/catalogmanager ./runcat.sh -cmd forgetAccounts -username
FUSION_APPS_HCM_ESS_APPID -cleanup -offline
/u01/APPLTOP/instance/BIShared/OracleBIPresentationServicesComponent/coreapplicatio
n_obips1/catalog/OracleBIApps
3. Start OBIPS (cd /u01/APPLTOP/instance/BIInstance/bin - ./opmnctlstartproc ias-
4. Start OBIPS (cd /u01/APPLTOP/instance/BIInstance/bin - ./opmnctlstartproc ias-
d) Secured UE Issue: When you come across scenarios where data is returned for
unsecured UE (such as Actions UE) but not for secured UE (such as Assignment UE)
Solution: Follow the steps indicated in Bug# 18669356. Indicative step is to run the ‘Retrieve
Latest Changes from LDAP’ job.
28 | P a g e
4 What if you still face an issue?

After performing the troubleshooting steps described above, if you still cannot identify the root
cause of the issue, you need to provide the following to help us identify the issue:
1. Extract Definition File

2. BIP Report Template
3. GMFZT Log output
4. ESS Log output
5. BIP Log output
6. Advanced logs, only if requested.
4.1 Extract Definition File

Steps:
1. Navigator > Manage HCM Extract Definition

2. Search and Select the Extract
3. On the Search Results, select the extract and click on ‘Export Extract’
4. Save the definition in the local file system and provide us the file
5. If you have used any Fast Formula in Criteria or Data Element, also include the Fast
Formula code.
Note: Do not provide the file generated by using the Export XSD button on Extract
Execution Tree page.
4.2 Provide us the E-Text or RTF template

Provide us the RTF/E-Text template (if any) you have uploaded to BI.
4.3 Enable GMFZT logging

Steps:
1. Navigator > Setup and Maintenance

2. Click on “All Tasks” tab and Search for task “Manage Payroll Process Configuration”
29 | P a g e
3. Click on Default Group, create a Logging level action parameter and set the value to
“GMFZT” as above.
4. Now run the extract that will log at this level. (refer to step 4.4 for accessing error log)
4.4 Provide us the ESS error logs

Steps:
1. In the Payroll Checklists WA, where you have submitted the extract run follow the steps
below to access the log details:
30 | P a g e
4.5 Provide us the BI logs

Steps:
1. Navigator > Scheduled Process
2. If you ran the extract process very recently, you can view them in the latest process list.
3. You can confirm the main ‘Archive Payroll Information and Generate Report’ process ID
in screen provided in (d) above.
4. All the process created after above process (Archive Payroll Information and Generate
Report), that are of type ‘Archive Integration with BI Publisher’ would ideally BI
processes and we will require BI logs associated with them.
Note: you can also confirm BI child job process id in the log extracted in step 4.4?
4.6 Advanced Debug logs (This is for Oracle Support Reference only)
This is required only if development team requests.
 Accessing Logs
 Flow Trouble Shooting
31 | P a g e
4.7 Checklist
Please answer the following checklist in the bug:
No Description Response
Yes, No, Not Applicable
1. Did you follow the step-by-step approach detailed in this
document?
2. While using child block, did you
• create a Block Link between the child block and parent
block?
• In the parent block record definition, did you set the
‘Next Block’ value to point to the child block?
3. Did you verify the causes listed in the trouble shooting
section of this document?
4. Did extract run successfully?
5. Did extract run successfully but XML is empty?
6. Did extract run successfully but XML output is not visible
in View Results?
7. Did extract run into error after attaching Delivery Option?
Did you troubleshoot following the steps listed? If not,
why?
8. Have you uploaded the Extract Definition File to
SR/BUG?
9. Have you uploaded the RTF/E-Text template file to
SR/BUG?
10. Have you enabled GMFZT option and attached the log
to SR/BUG?
11. Have you uploaded BI logs to SR/BUG?
32 | P a g e
Appendix
List of DBIs which are used mainly for predictive purposes and are not tested, preferably should
be avoided in HCM Extracts. Please check alternate DBIs with similar name. For example you
will have ‘Person Gender’ for ‘Gender’
1. Person Id - Person
2. Gender
3. Home city
4. Home country
5. Is employee
6. Marital status
7. Willing to relocate domestically
8. Willing to relocate internationally
9. Worker is separated from enterprise
10. Time since last marital status change
11. Tobacco user
12. Time until work permit or visa expiry
13. Average salary change
14. Latest salary change
15. Reason for latest salary change
16. FTE value
17. Time since latest salary change
18. Time until next salary review
19. Time since stock options received
20. Ratio of vested to unvested options
21. Current performance
22. Current appraising manager
23. Current manager rating
24. Change in current performance
25. Difference between manager rating and self rating
26. Current self rating
27. Previous manager rating
28. Number of grade changes in last 2 years
29. Number of manager changes in last 5 years
30. Disabled
31. Time until contract expiry
32. Has second passport
33. Nationality
34. Number of stock options compared to others on the same grade
35. Worker's stock options compared to peers
36. Potential profit on stock
37. Manager's performance
38. Time until the next performance review
33 | P a g e
39. Worker's performance compared to peers

40. Amount of leave in previous year
41. Total leave taken
42. Time since last leave
43. Amount of sickness in current year
44. Increase in sickness over previous year
45. Amount of sickness in previous year
46. Increase in sickness absences over previous year
47. Number of sickness absences in previous year
48. Time since last sickness
49. Length of service
50. Current assignment status
51. Average time per grade
52. Average time per job
53. Average time per department
54. Average time per position
55. Number of grade changes
56. Number of department changes
57. Current enterprise
58. Current grade
59. Current job
60. Current legal employer
61. Current location
62. Current manager
63. Current department
64. Current position
65. Worker category
66. Legislation
67. Average time with each manager
68. Time in current grade
69. Time in current job
70. Time with current manager
71. Time in current department
72. Time in current position
73. Time since last probation ended
74. Normal end time
75. Normal start time
76. Normal working hours
77. Age
78. Ethnicity
34 | P a g e
Oracle Corporation, World Headquarters Worldwide Inquiries

500 Oracle Parkway Phone: +1.650.506.7000
Redwood Shores, CA 94065, USA Fax: +1.650.506.7200
CONNECT W ITH US
blogs.oracle.com/oracle Copyright © 2014, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only, and the
contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other
facebook.com/oracle warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
fitness for a particular purpose. We specifically disclaim any liability with respect to this document, and no contractual obligations are
twitter.com/oracle formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any
means, electronic or mechanical, for any purpose, without our prior written permission.
oracle.com
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and
are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are
trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. 0514
35 | P a g e

HCM Extracts Approach and Troubleshooting Guide

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

HCM Extracts Approach and Troubleshooting Guide

Caricato da

Copyright:

Formati disponibili

An Oracle Whitepaper

HCM Extracts: Step-by-Step Approach and

Fusion HCM Extracts: Step-by-Step Approach and

08-Apr-2014 Shesha Shila Bharadwaj R 0.1 First Release

The guide is applicable for Release 7 PB7 onwards.

Documentation links on MOS

2 A step-by-step approach to create an HCM Extract ............................................................ 6

2.1 Design the Extract Structure ........................................................................................ 6

2.2 Define the Extract ........................................................................................................ 8

2.3 Submit an Extract without Delivery Options.................................................................. 9

2.4 Create an empty BI Publisher Report ........................................................................... 9

2.5 Create BIP Template and Test ....................................................................................10

2.6 Add Layout to BI Report and Test ...............................................................................10

2.7 Preview Extract Output in BIP .....................................................................................12

2.8 Schedule the Report to Check BIP Delivery Status .....................................................12

2.9 Configure Delivery Options .........................................................................................16

2.10 Submit an Extract........................................................................................................18

3 Troubleshooting Steps .......................................................................................................19

3.1 Known Issues .............................................................................................................19

3.2 Issues with Importing Extract Definitions .....................................................................19

3.3 Flexfield DBIs are not Visible ......................................................................................20

3.4 Extract Run Errors ......................................................................................................20

3.5 Extract without Delivery Options Errors When Run .....................................................20

3.6 Extract Runs to Success, but XML Output is empty ....................................................22

3.7 Successful Extract with Partial XML Output ................................................................22

3.8 Successful Extract with Duplicate Rows in XML ..........................................................23

3.9 Successful Extract with XML not Visible in View Results.............................................23

3.11 Other issues................................................................................................................27

4 What if you still face an issue? ...........................................................................................29

4.1 Extract Definition File ..................................................................................................29

4.2 Provide us the E-Text or RTF template .......................................................................29

4.3 Enable GMFZT logging ...............................................................................................29

4.4 Provide us the ESS error logs .....................................................................................30

4.5 Provide us the BI logs .................................................................................................31

4.7 Checklist .....................................................................................................................32

2 A Step-by-Step Approach to Create an HCM Extract

2.1 Design the Extract Structure

 Link the parent and child blocks by defining a block link

Frequently used UEs:

User Entity Purpose Comments

PER_EXT_SEC_ORGANI Used to retrieve organizations You need to explicitly filter

PER_EXT_SEC_PERSON Used to retrieve all the Person

PER_EXT_SEC_ASSIGN Used to retrieve all the Person,

PER_EXT_PAY_EMPLOY Used to retrieve all the Person,

PER_EXT_SEC_POSITIO Used to retrieve Position, Jobs

PER_EXT_RESET_UE It’s a dummy container used to It’s also used to reset

PER_EXT_SEC_ASSIGN Used to retrieve historical

2.2 Define the Extract

1. Create the extract as per the design above.

2.3 Submit an Extract without Delivery Options

2.4 Create an empty BI Publisher Report

Refrain from modifying the globalReportsDataModel.

2.5 Create BIP Template and Test

Sample Screenshot of the Template Viewer

2.6 Add Layout to BI Report and Test

Layout Name Free text to identify the underlying report layout.

Note: This filename should not be considered while configuring

3. Save the report.

2.7 Preview Extract Output in BIP

2.8 Schedule the Report to Check BIP Delivery Status

c) Follow below steps to configure Email/SFTP

iii) Submit the process.

2.9 Configure Delivery Options

1. Return to the extract definition and define the delivery option.