Documente Academic
Documente Profesional
Documente Cultură
Translation Data 41
Translation-File Discriminators 42
Updating Translation Data 42
Monitoring Progress 48
Import and Load Data User Interface 48
Extracting Data 53
Best Practices 57
File Shape 57
Data Migration 57
Ongoing Interfaces 57
Additional Help 58
HCM Data Loader Data Set Status Diagnostic 58
Glossary 62
Rel 9.7 Review HCM Data Loader Configuration Until this release only UTF-8 encoding is supported. From Release 9.7 you
Parameters can specify which file encoding type used in the new File Character Set
parameter.
Rel 9.7 Stopping Processing The Cancel button is renamed Stop to remove confusion. Stopping a
process will not rollback objects committed to Oracle HCM Cloud.
Rel 9.5 Error! Reference source not found. While HCM Data Loader availability is controlled there is a one-time setup
step to provide access to HCM Data Loader.
Rel 9.5 Specifying the HCM Data Loader Scope HCM Data Loader cannot be used in parallel with HCM File-Based Loader
and HCM Spreadsheet Data Loader to maintain the same business object.
A new HCM Data Loader Scope parameter has been introduced to control
how these tools are used.
Rel 9.5 Reviewing Business Objects A new user interface allows you to review the business objects registered
with HCM Data Loader.
Rel 9.5 Generating and Modifying Template Files The ability to generate environment-specific business object template files
that will include attributes to load data into your configured flexfield
segments.
Supports important business objects belonging to key Oracle HCM Cloud products, including
Oracle HCM Cloud Global Human Resources, Compensation, Absence Management, Performance
Management, Profile Management, Global Payroll, Talent and Workforce Management.
Is available in cloud, on-premises, and on-demand environments.
Supports one-time data migration, maintenance of Oracle HCM Cloud data via upload, and
coexistence scenarios, where core HR data exists outside Oracle HCM Cloud.
Provides a comprehensive user interface for initiating data upload, monitoring progress, and
reviewing errors, with real-time information provided for both the import and load stages of its
processing.
Supports multithreaded processing, which enables you to upload complete system extracts without
severe performance impacts. HCM Data Loader manages references among objects that are
processed on separate threads.
Includes a delimited-file reader that can identify file contents from metadata included in the file that
you upload. This feature enables you to perform partial or incremental loads, thereby minimizing
the related processing.
Supports user keys for all objects. Knowledge of Oracle HCM Cloud internal IDs is not required.
Enables bulk update of objects, regardless of whether they were created using HCM Data Loader.
Loads all data files from the Oracle WebCenter Content server, which provides a single point of
entry to Oracle HCM Cloud.
Can be initiated using a web service call, which enables you to automate data upload.
Is function-rich. For example, you can upload:
o Current and historical records for date-effective objects. You determine the amount of
history to load.
o End-dated, terminated, or inactive records.
o Translated attributes in multiple languages. The WE8ISO8859P1 character set (West
European 8-bit ISO 8859 Part 1) with UTF-8 encoding is supported.
o Descriptive flexfields (DFFs) and extensible flexfields (EFFs).
o Hierarchical tree data, e.g. Organization, Department Trees.
o Attachments and pictures.
o Data from multiple sources. You can include source-system references in uploaded data.
1. You place a zip file containing your data on the WebCenter Content server.
2. You submit a request to HCM Data Loader to import and load the zip file of data. For this step, you can
use either the HCM Data Loader interface or the HcmCommonDataLoader web service.
3. HCM Data Loader decompresses the zip file and imports individual data lines to its stage tables, grouping
those distinct file lines into Oracle HCM Cloud business objects.
4. It then calls the relevant logical object interface method (delivered in product services) to load objects to
the Oracle HCM Cloud application tables.
5. Any errors that occur during the import or load phase are reported in the HCM Data Loader interface.
6. Having reviewed import and load errors in the HCM Data Loader interface, or via the Data Set Summary
extract, you correct them in your source data. You load a new zip file containing the corrected data to the
WebCenter Content server.
You repeat this process until all of the data is successfully loaded.
Adding the HCM Data Loader Duty to the Human Capital Management Integration Specialist Job Role
Sign in as IT Security Manager.
Go to the Setup and Maintenance work area, Overview page, All Tasks tab.
3. Select Search - External Roles under the Search and Create heading.
4. On the Search External Roles page, search for the Human Capital Management Integration
Specialist job role.
5. Select the job role in the Search Results, and click Open Role.
7. Add the duty role HCM Data Load Duty. (Click + Map, select hcm, search for the HCM Data Load Duty
duty role, select it, and click Map Roles.)
Generate the Data Security Policies for the Roles that Inherit this Duty Role
1. Return to Oracle HCM Cloud Applications and navigate to the Setup and Maintenance work area.
3. Search for your Human Capital Management Integration Specialist job role, and then click Assign.
4. Proceed through the pages in the flow until you get to the Review page, and then click Submit.
5. Click Done.
HCM Data Loader resolves this by supporting four different key types, for all types of object reference:
User Key
Oracle HCM Cloud Surrogate ID
Source Keys
Oracle HCM Cloud GUID (Globally Unique Identifier)
Figure 1: User key: Create Department - the user key is the organization name
This key solution is suitable for the initial creation and updates of a logical object.
User keys are part of the business object definition and are always mandatory when creating a logical object,
regardless of how you create it.
You must take care when using user keys to reference a logical object to update. The user key value can change
over time and some user key attributes are translatable.
When a business object is bound by another, the user key will need to also include the user key for its parent, for
example, Jobs are always part of a Set, so JobCode alone would not uniquely identify a job, the SetCode must be
part of the user key for Job. Job grades are for a specific job, so the user key for a job grade would include the user
key for the parent job too, e.g. GradeCode, JobCode, SetCode.
The user key is recommended when referencing or maintaining an Oracle HCM Cloud HCM record that was not
created with a source key, or where the source key value is unknown.
By supplying a SourceSystemOwner, multiple source systems can provide data for the same business objects. For
example, you have Person data on both US and UK databases and these are to be combined into one Oracle HCM
Cloud system. By providing the SourceSystemOwner, the SourceSystemID does not need to be unique across both
source systems, just unique within the database it originates.
Source keys are only supported for integration-enabled business objects. Source keys are not held against the
created record, but in an Integration Key Map table.
The SourceSystemOwner value is validated against the HRC_SOURCE_SYSTEM_OWNER lookup. You will need
to add your source system name to this lookup prior to loading data using source system references
The source key is the recommended key type to use when performing data migration. You can then continue to
reference your Oracle HCM Cloud data using your source system identifier when maintaining or referencing that
data.
Object References
In HCM Data Loader the four key types can be used to identify:
For example, the rating model business-object comprises rating model, rating level, and rating category
components. The rating model component is the parent of the other two components. Each of these components is
made up of attributes such as rating model name, rating model code, rating level code, and so on.
The most complex business object supported by HCM Data Loader is the worker object, where 5 levels exist in the
object hierarchy. These range from the worker component at the top to assignment work measure, assignment
manager, assignment grade steps, and assignment extra information at level 5. By contrast, the person type object
comprises only the person type component.
When different components for the same business object are delivered together, HCM Data Loader groups them
into logical objects and loads the complete logical object in its entirety. It does not process the individual
components separately. If any part of the logical object fails validation, the whole logical object is rejected. By only
loading complete logical objects, you can be sure of exactly what data has been loaded, e.g. Job Accountant
loaded successfully, Job Accounts Clerk failed.
Terminology
In this Users Guide, the term object or business object always refers to the complete object (the parent component
and all child components). For example, Grade or Worker. The terms component or business-object component
refer to individual components of a business object. For example, Person Name or Work Relationship. The term
logical object refers to a group of related components that form one occurrence of a business object. For example,
the Grade IC1.
The zip file can contain one or more business object specific dat files. Each dat file corresponds to a single business
object, such as location, grade, worker, or salary. .Dat files should not be placed within folders in the zip file and
each dat file must have the name of a HCM Data Loader supported business object.
You only supply dat files for the business objects you are updating.
You can define the name of the zip file, but ensure that it is in alphanumeric characters, i.e. example a-z and 0-9.
Both upper and lowercase letters are acceptable.
The only acceptable folder names that can be included in the zip file are:
BlobFiles
ClobFiles
You place files to be loaded as attachments, or into large objects within these folders. You must ensure that file
names of these attachments or images are in alphanumeric characters. The data type of the attribute that is used to
load your attachment or large object data determines which folder to use. For example, the File attribute in
Documents of Record (DOR) is used for loading attachment files. It has a data type of BLOB, therefore, files to be
loaded as DOR attachments should be placed in the BlobFiles folder.
METADATA Definition Identifies the business-object component and its attributes for which values are included in the
data file.
MERGE Data Provides data to be added to Oracle HCM Cloud. You use the MERGE instruction whether
creating or updating objects. Oracle HCM Cloud identifies the appropriate action. The MERGE
instruction accepts complete or partial objects. The data supplied with the MERGE instruction is
merged into the existing Oracle HCM Cloud data.
Note: HCM Data Loader cannot accept multiple MERGE lines for the same record, in the same
dat file if that object is not date-effective. For example, you cannot create a Person Ethnicity
record and then correct it from the same file. As the object is not date-effective you are
attempting to correct the created data, not update it. In such a situation, you can supply only the
current data. Alternatively, you can insert a record in one file and update the record in a second
file.
HCM Data Loader does not process individual file lines, it groups related lines. This grouping
works for date-effective records because the file lines are processed in effective start date order.
DELETE Data Identifies business-object components to be purged from Oracle HCM Cloud HCM. You cannot
delete individual date-effective records; DELETE only supports the removal of the entire record.
Note: You should not provide DELETE instruction along with a MERGE instruction for the same
record. HCM Data Loader cannot guarantee in which order the two instructions will be
processed so you could either delete and create the record, or update and delete the record.
Caution: Deleted data cannot be recovered. It is recommended that you try and correct your
data rather than delete and recreate it.
SET Control Enables override of the default behavior for the file.
COMMENT Comment Adds a comment to the data file. The comment has no effect on processing.
File Discriminators
File discriminators are used to uniquely identify the business object component you wish to update. For example,
the available file discriminator for the Job business object:
Job Job
For example:
METADATA|Job|SetCode|JobCode|JobFamilyName|JobName|EffectiveStartDate|EffectiveE
ndDate
For example:
SET FILE_DELIMITER ,
COMMENT <comment>
Line Ordering
METADATA lines define which attributes are supplied in the file for a business object component. As such the
definition of a component must appear before any data for that component. You can include multiple METADATA
lines in the same business object file. However, each METADATA line must be for a different discriminator of the
owning business object hierarchy.
SET lines can override the default behavior of how the file is read, as such they must be supplied before any
METADATA lines. There are no other restrictions for line ordering in the file.
The order of the data lines in the file does not impact the order in which they are processed.
You should not supply a DELETE and MERGE line for the same logical object. There is no guarantee if the object
will first be deleted then created, or updated then deleted. Similarly, you must not provide multiple MERGE lines for
the same object. Provide only the latest data, unless the component supports date-effectivity, in which case you can
provide date-effective history for a logical object.
Reference a valid discriminator for the object specified by the dat file name.
Reference a unique discriminator for the object, you cannot supply multiple METADATA lines for the same
discriminator.
Only list valid attributes for that discriminator, attribute names are case sensitive.
Specify the attributes for at least one of the supported key mechanisms to uniquely reference the component
defined by the discriminator.
You can provide MERGE and DELETE instructions in the same file, but not for the same record. For example, when
loading jobs, you cannot provide a MERGE and a DELETE instruction for the same job.
Ensure that a manager is identified for every worker and that the information is accurate.
For jobs and positions, ensure that correct job codes and titles exist in the source systems.
For worker history, establish the accuracy of any historical data. Understand whether all historical data must be
uploaded or just key events, such as hire, promotion, and termination.
Preparing the source data in this way will minimize the problems that can occur when you upload data to Oracle
HCM Cloud. It will also make it less likely that you copy any inaccuracies to the new environment.
You may have performed this step during implementation of Oracle HCM Cloud.
When referring to these objects in the objects that you are loading, you use their user keys. (Alternatively, you can
use their surrogate IDs if available.)
HCM Data Loader provides business-object documentation for all supported objects. This documentation specifies
the user key that you can use to reference other objects. For example, the position component includes a reference
to the business unit object, which is not integration enabled. The position documentation identifies the business unit
name as its user key. Therefore, when loading a position component you can refer to the associated business unit
using the business unit name. (For more information about keys, see page 4.)
In Oracle HCM Cloud, LOVs are defined as lookups. You are recommended to review the predefined lookups and
make any updates before you attempt to load data that uses them. You may have completed this process during
implementation of Oracle HCM Cloud.
Relevant lookups are identified in the business-object documentation for HCM Data Loader supported objects.
To manage lookups, search for relevant tasks by entering Manage % Lookups in the Setup and Maintenance work
area. All available lookups tasks are listed. For example, to manage person lookups, select the Manage Person
Lookups task. On the Manage Person Lookups page, select a lookup to edit:
Ensuring that lookups contain appropriate values will reduce validation errors when you load data.
Settings Description
Limited Only business objects not supported by HCM File-Based Loader can be loaded using HCM Data
Loader.
Full HCM Data Loader is used for bulk loading data into all supported business objects. HCM File Based
Loader and HCM Spreadsheet Data Loader will be disabled.
The default value of this parameter is Limited. If you attempt to load data for a business object that is not supported
in the Limited mode, your whole data set will fail to process.
If you do not intend to use HCM File-Based Loader or HCM Spreadsheet Data Loader, you must set this parameter
to Full to ensure complete business object support by using HCM Data Loader.
1. Navigate to the Configure HCM Data Loader page (Setup and Maintenance - Configure HCM Data
Loader).
Restricted Objects
The HCM Data Loader registered objects that cannot be loaded using HCM Data Loader when the HCM Data
Loader Scope parameter is set to Limited are:
Global HR Action Reasons Grade Translation Organization
Action Reasons Translation Grade Step Translation Organization Translation
Actions Grade Ladder Position
Actions Translation Grade Ladder Translation Position Translation
Location Step Rate Translation Department Tree
Location Translation Grade Rate Department Tree Node
Job Family Grade Rate Translation Person Contact
Job Family Translation Job Person Contact Relationship
Grade Job Translation Worker
Global Payroll Element Entry
Compensation Salary Basis Salary
Absences Person Absence Entry Person Entitlement Detail
Talent Education Establishment Rating Category Translation Content Item Rating Description Translation
Education Establishment Translation Rating Level Translation Content Items Relationship
Rating Model Content Item Talent Profile
Rating Model Translation Content Item Translation Talent Profile Translation
File Character Set UTF-8 Character set for business object and attachment files.
Delete Source File Yes Delete the source file from the WebCenter Content server when processed.
Import Cache Clear Limit 2400 Number of file lines to be processed before the cache is cleared.
Import Commit size 100 Number of file lines to import between each commit.
Maximum Percentage of Import Errors 100 Percentage of file lines in error that can occur in a business object before the
import process stops for the object.
Maximum Percentage of Load Errors 100 Percentage of business-object instances in error that can occur for a business
object before the load process stops.
Data Error Stack Trace Occurrences 2 Maximum number of data error message occurrences on a processing thread for
by Thread which stack trace is recorded.
Complex Error Stack Trace 5 Maximum number of complex error message occurrences on a processing thread
Occurrences by Thread for which stack trace is recorded.
Load Cache Clear Limit 500 Number of business-object instances to be loaded from the stage tables before
the cache is cleared.
Maximum Concurrent Threads for 8 Maximum number of threads to run concurrently when loading data from the stage
Load tables to the application tables.
Load Group size 100 Number of business objects processed as a single unit of work by a single thread.
Figure 8: Initiate Data Load (Navigator - Data Exchange - Initiate Data Load)
From this page you can generate business object templates that provide METADATA lines for all components of the
business object hierarchy. These are useful to identify the attribute name to use for loading data. See the
Generating and Modifying Template Files section on page 19 for more information.
However, to load a business object successfully to Oracle HCM Cloud, you need to understand its Oracle HCM
Cloud structure, supported key systems, data formats, valid values, and required values.
Each spreadsheet is named for its top-level business object. For example, the file Location.xls includes the
information that you need about the location business object.
For complex business objects, the spreadsheet includes one tab for each component of the object. For example, the
Location.xls spreadsheet includes Location and Location Other Address tabs. Objects that support extensible
flexfields (EFFs) also include one tab for each EFF.
General information about a component appears at the top of its tab. This information includes:
The name of the Oracle HCM Cloud product that owns the object.
The name of the data file that you load (for example, Location.dat).
The components identifier (referred to as its discriminator). For example, LocationOtherAddress.
The date type for the components, such as, is it Simple Date, Effective Date, Multiple Changes Per Day
(MCPD), or not dated.
The level at which the component appears in its object hierarchy.
For child and grandchild components, the parent discriminator is also identified.
Following the general information about the component, these details appear for each attribute of the component:
Value Description
Attribute Name The attribute name as it appears in the data file that you load for the component.
Key Type For attributes that are key values or can be used as key values, identifies the key type. For example, user key, GUID or
Foreign Surrogate ID.
Alternate User Identifies the attributes that you can use in place of surrogate IDs. For example, the LocationId is the surrogate ID
Key for Surrogate attribute for Location. To refer to the location from another business object, you can use the LocationCode and
IDs SetCode user keys in place of the surrogate ID. The alternate user key for an attribute comprises all values that appear
in this column.
Integration Object For attributes that refer to other business objects, this column provides the name of the referenced object type. If that
Name object is not integration enabled, then the column contains the text not integration enabled. Integration enabled objects
can be referenced using Integration keys. Objects that are not integration enabled can only be referenced by user key
or Oracle HCM Cloud surrogate ID.
Data Type The data type of the attribute. For example, Number or String.
Primary Key Indicates whether the attribute is a component of the primary key. For example, for the location business object,
LocationId, EffectiveStartDate, and EffectiveEndDate are primary key values.
Mandatory Indicates whether the attribute is required. You must include required attributes when you create or update objects.
Lookup Name For attributes that are lists of values, provides the name of the Lookup. To see valid values for an attribute, review the
Lookup as described on page 13.
Oracle HCM Cloud GUID for the component. This value is generated in Oracle HCM Cloud and is described on
page 6.
Source key attributes SystemOwnerId and SourceSystemId values. For more information, see page 6.
For all business object components, the following information attributes appear at the end of the attribute list:
Source-system reference information (the table name, and up to 10 reference values). For more information,
see section Source-System References on page 35.
The spreadsheet for each supported business object also includes an Overview tab which summarizes the hierarchy
of components for the business object.
A COMMENT line, which identifies the business object, its version, and the file creation date.
A METDATA lines for each component of the business object hierarchy that you can load for the business
object. The METADATA line includes every attribute of the component, including environment specific
configured flexfield attributes.
You can generate business object template files and use them as the basis of your own data files.
To generate business object template files, navigate to the Data Exchange work area and select the Initiate Data
Load task.
Figure 9: Initiate Data Load page (Navigator - Data Exchange - Initiate Data Load)
Figure 10: Generating business object templates for all business objects
If you set the Module field to All, templates for every supported business object will be generated. Alternatively,
select a specific module to generate business object templates for.
To access template files individually from the Business Objects table, click on the file download icon ( ) in the File
column against the business object. Alternatively, you can download a single zip file for all the business object
templates you generated. To view all the processes submitted to generate template files, navigate to the Processes
tab. Click the file download icon ( ) for your process.
Figure 11: Review template files (Navigator - Data Exchange - Initiate Data Load - Processes)
HCM Data Loader validates every attribute name on every METADATA line. It also determines any potential
dependencies on other business objects in the same zip file by reviewing the attributes supplied in METADATA. For
example, if the Job.dat file contains the ValidGrade METADATA line with the GradeId attribute, HCM Data Loader
will assume that the Job.dat has a potential dependency on Grades.
You can improve the speed and efficiency of the import and load processes by only declaring the attributes that you
are supplying data for.
This is true for non-flexfield attributes only. For more information on lookup meaning values for lookup validated
flexfield segments, see page 35.
To set an existing numeric value to null, specify the tag #NULL as the attribute value.
Date YYYY/MM/DD
To set an existing date or time value to null, specify the tag #NULL as the attribute value.
This is because data for these data types tends to be very large. Additionally, content to be loaded directly (rather
than by attachment) may need to include new line characters, making it complex to include in the business object
dat file.
The business object documentation specifies the data type of all attributes. If you wish to load data into a CLOB
attribute you supply that data in a separate file and place that file in a folder named ClobFiles within the same zip
file as the business object dat file. Similarly if you wish to load data, or upload an attachment to a BLOB attribute,
you supply the data or file to attach in a folder named BlobFiles within the same zip.
Files within the ClobFiles and BlobFiles folders can have any name and most extensions are supported.
In the business object dat file you specify the file name for the CLOB / BLOB attribute. For example:
METADATA|DocumentAttachment|DocumentType|File|PersonNumber|..
MERGE|DocumentAttachment|Drivers License|file01.txt|23901|..
MERGE|DocumentAttachment|Drivers License|file02.txt|64235|..
For DocumentAttachment the File attribute has a BLOB data type, referenced files should be placed in the BlobFiles
folder:
Note: If the source key is not specified on the initial creation of a record it cannot be used later to update that record.
Note: You cannot use source keys for foreign object references, including parents, if you are not supplying a source
key for the local record.
The SourceSystemOwner attribute is common for all source keys supplied in a record, so the foreign objects being
referenced by source key must have the same SourceSystemOwner value to the record being merged.
Before source keys can be used the SourceSystemOwner value must be created in the
HRC_SOURCE_SYSTEM_OWNER, see page 14 for additional details.
Supply values for both the source key attributes; SourceSystemId and SourceSystemOwner
METADATA|Job|SourceSystemId|SourceSystemOwner|JobCode|JobName|SetCode|Effective
StartDate|EffectiveEndDate
MERGE|Job|12349|EBS-UK|SE|Software Engineer|COMMON|2010/01/01|4712/12/31
Append the (SourceSystemId) hint to the surrogate ID attribute for the foreign object being referenced. In this
example Job, this Job must have been created using HCM Data Loader with the source key supplied.
METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobId(SourceSystemId)|Effe
ctiveStartDate|EffectiveEndDate
MERGE|Assignment|234234|EBS-UK|12349|2013/01/01|4712/12/31
Source keys can only be used for integration-enabled foreign objects. The business object documentation identifies
which foreign objects are integration enabled.
The user key attributes will be mandatory when you first create a record and mandatory for updates unless you
supply a different key type to uniquely reference the record being updated.
Caution: Some user keys can change over time, this can make using the user key for historical references
challenging.
If you are loading date-effective history for a business object component where the user key does change, you must
also supply a source key. This will allow HCM Data Loader to correctly group related date-effective records to
correctly form the object being loaded.
User keys can comprise of multiple attributes, all must be supplied if no other key type is being used:
METADATA|Job|JobCode|JobName|SetCode|EffectiveStartDate|EffectiveEndDate
MERGE|Job|SE|Software Engineer|COMMON|2010/01/01|4712/12/31
Figure 16: Supplying the user key for the local record
In this example the Assignment is uniquely referenced by a source key. However, the Job is referenced by its user
key:
Oracle HCM Cloud surrogate ID cannot be assigned when you create data in Oracle HCM Cloud. It generates them
internally at commit, so for new records either a source key or user key must be supplied.
METADATA|Job|JobId|JobName|EffectiveStartDate|EffectiveEndDate
MERGE|Job|13413|Software Engineer - Java|2013/01/01|4712/12/31
Figure 18: Supplying the Oracle HCM Cloud surrogate ID for the local record
In this example the Assignment is uniquely referenced by a source key. However, the Job is referenced by its
Fusion Surrogate ID:
METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobId|EffectiveStartDate|E
ffectiveEndDate
MERGE|Assignment|234234|EBS-UK|13413|2013/01/01|4712/12/31
Figure 19: Supplying the Oracle HCM Cloud surrogate ID for a foreign object
When supplying an Oracle HCM Cloud GUID value to uniquely reference the record being merged/deleted, the
attribute name is identical for all business object components: GUID.
METADATA|Job|GUID|JobName|EffectiveStartDate|EffectiveEndDate
MERGE|Job|2342UJFHI2323|Software Engineer - Java|2013/01/01|4712/12/31
Figure 20: Supplying the Fusion GUID for the local record
Append the (GUID) hint to the surrogate ID attribute for the foreign object being referenced. In this example Job:
METADATA|Assignment|SourceSystemId|SourceSystemOwner|JobId(GUID)|EffectiveStart
Date|EffectiveEndDate
MERGE|Assignment|234234|EBS-UK|2342UJHFI2323|2013/01/01|4712/12/31
Figure 21: Supplying the Oracle HCM Cloud GUID for a foreign object
For more details and examples of how these modes will impact your data see the Maintaining Existing Date-
Effective Data section on page 36.
Date effective records have common attributes that are normally mandatory when loading data:
EffectiveStartDate The start date for the attribute values, this value is always mandatory for date-effective components.
EffectiveEndDate The end date for the attribute values. If left blank the end of time is defaulted, meaning the date effective
record will continue on with no end
EffectiveSequence When multiple changes per day (MCPD) can be recorded the EffectiveSequence provides the order in
which the changes occurred.
EffectiveLatestChange A Y/N flag, for MCPD records this attribute indicates which record is the latest for the EffectiveStartDate.
METADATA|Job|EffectiveStartDate|EffectiveEndDate|Attribute1|Attribute2|..
MERGE|Job|1950/01/01|2012/03/04|W|X|..
MERGE|Job|2012/06/02|2013/02/03||Y|..
MERGE|Job|2013/02/04|4712/12/31|Z||..
1950/01/01 2012/03/04 W X
2012/06/02 2013/02/03 W Y
2013/02/04 Z Y
Attribute 1 will retain the W value on the second row, as no value was specified, similarly attribute2 will retain the Y
value on the final row.
For example:
METADATA|Job|EffectiveStartDate|EffectiveEndDate|Attribute1|Attribute2|..
MERGE|Job|1950/01/01|2012/03/04|W|X|..
MERGE|Job|2012/06/02|2013/02/03|#NULL|Y|..
MERGE|Job|2013/02/04|4712/12/31|Z|#NULL|..
1950/01/01 2012/03/04 W X
2013/02/04 Z (null)
It is advisable to use the #NULL token to ensure a null value in Oracle HCM Cloud. Leaving an attribute with no
value will roll forward any existing value that attribute may have.
There is no restriction on the order in which date effective records are provided in the dat file, but there must be no
break in the dates.
Example:
This is not valid as the information between 5-Mar-2012 and 1-Jun-2012 is missing.
METADATA|Job|EffectiveStartDate|EffectiveEndDate|JobCode|..
MERGE|Job|1950/01/01|2012/03/04|ACC1|..
MERGE|Job|2012/06/02|||ACC1|..
HCM Data Loader groups your distinct file lines into logical objects, a logical object being one occurrence of the
business object. For example, a Job or a Worker. The logical object grouping is performed on the unique key for the
component, so the key value must be the same across the date-effective history. Any of the four keys types can be
used to uniquely identify the records.
Example:
This is not valid as the SourceSystemId used to uniquely identify Job ACC1 changes with the date-effective history.
METADATA|Job|SourceSystemId|EffectiveStartDate|EffectiveEndDate|JobCode|..
MERGE|Job|JB394_19500101|1950/01/01|2012/03/04|ACC1|..
When reporting multiple changes on the same effective start date, the EffectiveSequence value must start at 1 and
increase sequentially. The same EffectiveSequence value cannot be repeated for the same logical object on the
same date, nor can there be any gaps. If there is only one change for an effective start date the EffectiveSequence
will always be 1. You cannot leave the EffectiveSequence blank when providing multiple changes per day. Without
this information there is no guarantee in which order the records starting on the same EffectiveStartDate will be
processed.
Example:
This is not valid as each sequence starts at zero, and the sequence 2 is missing.
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veEndDate|..
MERGE|Assignment|2724|2010/06/08|0|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|0|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|3|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|4|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1||..
When reporting multiple changes on the same effective start date, the latest record should have an
EffectiveLatestChange value of Y. All earlier records should have an N value. This attribute is always mandatory for
MCPD records.
If there is only one change for an effective start date, the EffectiveLatestChange will always be Y.
Example:
This is not valid as the EffectiveSequence of 3 is the latest change but the EffectiveLatestChange value is not Y.
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|1|Y|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|1|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|2|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|3|N|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1|Y||..
For MCPD records that are not the latest change, the EffectiveEndDate must match the EffectiveStartDate.
When reporting multiple changes on the same effective start date, all MCPD records that are not the latest change
should have an EffectiveEndDate matching the EffectiveStartDate.
This is not valid because the EffectiveEndDate of those records with an EffectiveLatestChange of N have an
EffectiveEndDate that does not match the EffectiveStartDate.
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|1|Y|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|1|N|2012/06/01|..
MERGE|Assignment|2724|2012/03/04|2|N|2012/06/01|..
MERGE|Assignment|2724|2012/03/04|3|Y|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1|Y||..
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effectiv
eLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|1|Y|2012/03/03|..
MERGE|Assignment|2724|2012/03/04|1|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|2|N|2012/03/04|..
MERGE|Assignment|2724|2012/03/04|3|Y|2012/06/01|..
MERGE|Assignment|2724|2012/06/02|1|Y||..
Simply supply the data that has changed with the effective start date the change became effective.
METADATA|Job|SourceSystemId|SourceSystemOwner|EffectiveStartDate|EffectiveEndDat
e|ActiveStatus
MERGE|Assignment|2724|EBS-UK|2015/01/01||I
Note: The EffectiveEndDate value has not been supplied ensuring that this change will take effect until the end of
time.
For MCPD records, if you do not know the next available sequence number you can generate it by simply leaving
the EffectiveSequence attribute blank.
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effectiv
eLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08||Y|4712/12/31|..
By supplying an EffectiveSequence value that already exists you will be correcting the existing record, not creating a
new MCPD split. To correct MCPD records you must supply all MCPD attributes to uniquely identify the MCPD
record to correct.
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effectiv
eLatestChange|EffectiveEndDate|..
MERGE|Assignment|2724|2010/06/08|3|N|4712/12/31|..
Reserved Characters
By default, these characters are reserved and cannot be included in attribute values:
Delimiter (pipe |)
Escape (slash \)
To include the new line and pipe characters in attribute values, you precede them immediately with the escape
character (slash \). For example:
METADATA|Address|AddressLine1
MERGE|Address|TheSteading\|Kier Allan
To include the new-line character in a value, you specify \n. For example:
METADATA|Address|AddressLine1
MERGE|Address|TheSteading\nKier Allan
The format of the SET command for overriding reserved characters is:
The new value can be up to 10 characters. For example, you could set the new-line character to newline and the file
delimiter to comma (,) using the following SET commands:
SET FILE_DELIMITER ,
SET FILE_NEW_LINE newline
METADATA,Address,AddressLine1
MERGE,Address,TheSteading\newlineKier Allan
Flexfields
Using HCM Data Loader, you can load both descriptive flexfield (DFF) and extensible flexfield (EFF) data.
After configuring your descriptive and extensible flexfields, navigate to the Initiate Data Load page to generate a
template for your object. The generated template will include in the METADATA lines all the attributes required to
successfully load data into your configured flexfields. For more information about generating business object
templates, refer to page 19.
This section explains the concepts that are common to supplying descriptive and extensible flexfield data, followed
by the specific information required for each flexfield type.
Flexfield Code
If supplying flexfield attribute values, in addition to providing the flexfield attribute names, you must also supply the
flexfield code in the METADATA line, in the format:
The available flexfield codes will be included in your generated template file.
Both descriptive and extensible flexfields have one or more contexts. This attribute will be used to supply the
context information on your MERGE lines.
Flexfield attribute names are derived from the name you configured the flexfield segment with. However, they must
also be provided with a hint that tells HCM Data Loader which flexfield the attribute belongs to, and which context it
is applicable to:
DFF Example:
The Contract component of the Worker business object supports both the PER_CONTRACT_DF and
PER_CONTRACT_LEG_DDF descriptive flexfields.
CN _CONST_PROB_DATE (PER_CONTRACT_LEG_DDF=CN)
CN _NDA (PER_CONTRACT_LEG_DDF=CN)
CN _COMPETITION_CLAUSE (PER_CONTRACT_LEG_DDF=CN)
CN _NOTICE_DURATION_UNIT (PER_CONTRACT_LEG_DDF=CN)
If you were to generate a Worker.dat template file, the Contract METADATA line would include these attributes:
EFF Example
The Job hierarchy provides the JobLegislative extensible flexfield. This has the following configuration:
CA _NOC_CODE (PER_JOBS_LEG_EFF=CA)
CH _POSITION_TYPE (PER_JOBS_LEG_EFF=CH)
FR _ECAP_JOB (PER_JOBS_LEG_EFF=FR)
FR _INSEE_PCS_EXT_CODE (PER_JOBS_LEG_EFF=FR)
If you were to generate a Worker.dat template file, the Contract METDATA line would include these attributes:
You can load data for all attributes of any DFF defined for all HCM Data Loader registered objects.
Descriptive FlexFields (DFF) extend a business object, as such DFF attributes can be provided with the core
attributes for the business object component.
To supply DFF data for a business object component simply include the Flexfield Code and Descriptive Flexfield
attributes that you wish to load for to the METADATA line of the business object component. These are available
from your generated business object template file.
METADATA|Job|FLEX:PER_JOBS_DFF|JobCode|ActiveStatus|FullPartTime|MedicalCheckupR
equired|RegularTemporary|EffectiveStartDate|EffectiveEndDate|Name|SetCode|JobFam
ilyName|_JOB_LEVEL(PER_JOBS_DFF=US)
Figure 27: Defining DFF attributes in METADATA
The DFF attributes can be defined anywhere on the METADATA line, they do not need to appended to the end.
For each supported DFF for a business object component, a record can only have one context at any point in time.
The context for each record must be supplied against the Flexfield Code for the DFF.
Example:
METADATA|Job|FLEX:PER_JOBS_DFF|JobCode|ActiveStatus|FullPartTime|MedicalCheckupR
equired|RegularTemporary|EffectiveStartDate|EffectiveEndDate|Name|SetCode|JobFam
ilyName|_JOB_LEVEL(PER_JOBS_DFF=US)
MERGE|Job|US|ACC|A|F|N|R|2000/01/01|4712/12/31|Accountant|COMMON|Finance|1
Figure 28: Supplying Descriptive Flexfield Data
Supplying DFF MERGE Lines for Multiple Flexfield Codes and Contexts
When multiple DFFs are supported for the same business object component, the data can be loaded at the same
time:
METADATA|Contract|AssignmentId|ContractId|EffectiveStartDate|EffectiveEndDate|F
LEX:PER_CONTRACT_DF|FLEX:PER_CONTRACT_LEG_DDF|_CONTRACT_GLB(PER_CONTRACT_DF=Glo
bal Data Elements) |_Currency(PER_CONTRACT_DF=CONTRACT_DF)
|_MAIN_CONTRACT(PER_CONTRACT_LEG_DDF=CH)|_CONST_PROB_DATE(PER_CONTRACT_LEG_DDF=
CN)|_NDA(PER_CONTRACT_LEG_DDF=CN)|_COMPETETION_CLAUSE(PER_CONTRACT_LEG_DDF=CN)|
_NOTICE_DURATION_UNIT(PER_CONTRACT_LEG_DDF=CN)
MERGE|Contract|E8732|39987|2013/12/14|2014/03/04|CONTRACT_DF|CN|Contract Glb
value|USD|Contract Data|||
Figure 29: Supplying Descriptive Flexfield Data for multiple flexfield codes
Category Code
In addition to the Flexfield Code, extensible flexfields also have a Category Code. This will be provided in your
generated template file with an attribute name of EFF_CATEGORY_CODE.
Extensible Flexfields (EFF) are not an extension of a business object component, but a separate component in the
business object hierarchy.
To supply EFF data simply include the METADATA line for the EFF component, removing any attribute names you
will not be supplying data for.
METADATA|JobLegislative|EFF_CATEGORY_CODE|FLEX:PER_JOBS_LEG_EFF|JobId(SourceSys
temId)|JobCode|SetCode|EffectiveStartDate|EffectiveEndDate|SourceSystemOwner|So
urceSystemId|LegislationCode|_EEO1_CATEGORY(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_FLSA
_STATUS(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_INSEE_PCS_CODE(PER_JOBS_LEG_EFF=FR)|_ECA
P_JOB(PER_JOBS_LEG_EFF=FR)|_LINE_OF_PROGRESSION(PER_JOBS_LEG_EFF=HRX_US_JOBS)
An extensible flexfield record can only have one context at any point in time. The context for each record must be
supplied against the Flexfield Code for the EFF.
Example:
METADATA|JobLegislative|EFF_CATEGORY_CODE|FLEX:PER_JOBS_LEG_EFF|JobId(SourceSys
temId)|JobCode|SetCode|EffectiveStartDate|EffectiveEndDate|SourceSystemOwner|So
urceSystemId|LegislationCode|_EEO1_CATEGORY(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_FLSA
_STATUS(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_INSEE_PCS_CODE(PER_JOBS_LEG_EFF=FR)|_ECA
P_JOB(PER_JOBS_LEG_EFF=FR)|_LINE_OF_PROGRESSION(PER_JOBS_LEG_EFF=HRX_US_JOBS)
MERGE|JobLegislative|JOB_LEG|HRX_US_JOBS|OCT18EFF1|OCT18EFF1|COMMON|1990/01/01|
4712/12/31|HRC_SQLLOADER|OCT18EFF1_LEG1|US|TECHNICIAN|EXEMPT||| Testing EFF
MERGE|JobLegislative|JOB_LEG|FR|OCT18EFF1|OCT18EFF1|COMMON|1990/01/01|4712/12/3
1|HRC_SQLLOADER|OCT18EFF1_LEG2|FR|||387b|N|
Unlike other components of the business object hierarchy, EFF MERGE lines cannot be supplied in isolation, but,
must be accompanied by a parent record.
METADATA|Job|FLEX:PER_JOBS_DFF|gender_Display(PER_JOBS_DFF=JOBCONTEXT1)|..
MERGE|Job|JOBCONTEXT1|Male|..
MERGE|Job|JOBCONTEXT1|Female|..
Source-System References
You can include source-system references in each data line in a file.
Source-system references are optional. They enable you to record the source-system database table name, column
names, and attribute values. These details are visible in the HCM Data Loader interface. Therefore, if an object fails
to load, you can easily identify the data source.
Source-System Names
You specify source-system names in the relevant METADATA line.
To specify the source-system table name, you add to the METADATA line:
SourceRefTableName=<table name>
You can specify up to 10 source-system column names in the same METADATA line using the SourceRef001 to
SourceRef010 tags.
For example:
METADATA|Job|SourceRefTableName=PER_JOBS|SourceRef001=JOB_ID|SourceRef002=EFFEC
TIVE_START_DATE|SourceRef003=EFFECTIVE_END_DATE
Source-system references can appear anywhere in the METADATA line after the instruction and discriminator tags.
Source-System Values
Supply the source-system values on each data line, ensuring that they appear in the order specified on the
METADATA line.
In data lines you must leave the source-system table name blank. This value appears in the METADATA definition
only.
For example:
METADATA|Job|SourceRefTableName=PER_JOBS|SourceRef001=JOB_ID|SourceRef002=EFFEC
TIVE_START_DATE|SourceRef003=EFFECTIVE_END_DATE
MERGE|Job||135|2010/01/01|4712/12/31
MERGE|Job||136|2010/01/01|4712/12/31
When supplying changes for date-effective records there is the potential for updates to impact multiple date-effective
rows. Care must be taken if your change predates existing data for your record.
For example:
If you supply an update with an Effective Start Date of 2011/01/01 and no Effective End Date is supplied, a new
date-effective split will be generated on the 1st January 2011 but both the 10th January 2012 and 4th March 2012
records will be impacted. How these records will be updated depends on the date-effective maintenance mode.
Retain - Retains all existing date-effective records. This mode is recommended when you are supplying an
incremental update to an existing record.
Replace - Removes existing date-effective splits for the date range specified. This mode is useful during
data migration, when you are uploading the complete data for a record.
Both modes will generate a new date-effective split if you specify an effective start or end date that is new, i.e. no
date-effective split exists for that date.
Both modes will only update the attributes that you have supplied values for. If you want to ensure a null value
exists, then make use of the #NULL token. See Setting Not Null Attribute Values to Null, on page 21.
The following information provides guidance on the functionality that these modes provide. However, not all
business objects fully support these modes. See the business object specific documentation for more information.
Figure 33: Setting the update mode for future dated records
To retain future dated records you must include a SET command to override the default behavior:
SET PURGE_FUTURE_CHANGES N
When HCM Data Loader is running in retain mode, you can choose to:
Assignment Example
ESD Seq EED Action Code Job Grade Location Normal Hours
Update the working hours on the 10th Jan 2012 retaining future dated values
SET PURGE_FUTURE_CHANGES N
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|ActionCode|NormalHours
MERGE|Assignment|2724|2012/01/10||Y|#RETAIN|ASG_CHANGE|37.5
ESD Seq EED Action Code Job Grade Location Normal Hours
Note: The EffectiveSequence attribute was not supplied with a value to ensure the next MCPD split was assigned to
this change. If you want to start at an existing MCPD split, specify the EffectiveSequence and
EffectiveLatestChange values for that MCPD record.
ATTENTION: This is the only recommended action for MCPD records, or any record with a mandatory ActionCode.
By attempting to roll forward any changes over future dated records, you are likely to corrupt the ActionCode for
each future dated record in your specified date range.
If you had not supplied the #RETAIN tag, but instead left the EffectiveEndDate unspecified or had a value of
4712/12/31, to ensure the change was applied until the end of time, you would get a very different result:
Update the working hours on the 10th Jan 2012 overwriting future dated values:
SET PURGE_FUTURE_CHANGES N
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|ActionCode|NormalHours
MERGE|Assignment|2724|2012/01/10||Y||ASG_CHANGE|37.5
ESD Seq EED Action Code Job Grade Location Normal Hours
As the Action Code is a mandatory attribute that you have supplied a value for, the supplied value will overwrite the
existing Action Code for all future dated records.
Note: This action is not reversible. If you supply attribute values that span existing date-effective splits they will all be
updated with every attribute value supplied.
Specify the effective end date when the change should stop
Specify that the change should continue until the end of the object
If you know when your change should end, supply that date in the EffectiveEndDate attribute.
You can apply a change to RegularTemporary from 4th March 2011 to 4th April 2014 by including these lines in the
Job .dat file:
SET PURGE_FUTURE_CHANGES N
METADATA|Job|SourceSystemId|EffectiveStartDate|EffectiveEndDate|ReqularTemporar
y
MERGE|Job|45346|2011/03/04|2014/04/04|R
A new date-effective split will be created for both the start and end dates. Only the RegularTemporary attribute was
supplied with a value, so only that attribute is updated for the date-range, other attributes retain their existing value.
Correct All Future Dated Records for the Life of the Object
Most objects do not end, they are terminated, or become inactive. However, you can stop a few objects in time, for
example, element entries. The #ALL tag provides a safe way of specifying that you want all future dated records to
be corrected with your changes, regardless of the end date of the object.
You can apply a change to RegularTemporary from 4-Mar-2011 until the end of the Job by including these lines in
the Job .dat file:
SET PURGE_FUTURE_CHANGES N
METADATA|Job|SourceSystemId|EffectiveStartDate|EffectiveEndDate|ReqularTemporar
y
MERGE|Job|45346|2011/03/04|#ALL|R
By default future dated changes will be replaced. However, if you want to ensure this behavior then supply this SET
command:
SET PURGE_FUTURE_CHANGES Y
ESD Seq EED Action Code Job Grade Location Normal Hours
Update the working hours on the 10th Jan 2012 replacing future dated values
SET PURGE_FUTURE_CHANGES Y
METADATA|Assignment|SourceSystemId|EffectiveStartDate|EffectiveSequence|Effecti
veLatestChange|EffectiveEndDate|ActionCode|NormalHours
MERGE|Assignment|2724|2012/01/10||Y||ASG_CHANGE|37.5
ESD Seq EED Action Code Job Grade Location Normal Hours
A new date-effective split is generated for the new EffectiveStartDate of 10th Jan 2012 supplied.
The date-effective records that existed after that date are replaced by this change.
Existing attribute values that pre-date the change and where new values have not been supplied will continue on the
new record. To explicitly remove existing values the #NULL token must be supplied.
Translation Data
In environments where multiple languages are enabled, you can load translated objects. HCM Data loader supports
the WE8ISO8859P1 character set with UTF-8 encoding.
For example, if you create a record for the Sales Manager job in an environment where US English is the base
language and French, German, and Spanish are enabled, then the object is created as follows:
Once this object is successfully created, you can load a single translation data file (JobTranslation.dat) to correct the
French, German, and Spanish translations of the job name. You can load the translations in separate files, one per
language, if you prefer.
You can deliver translation files either in the same zip file as the original object or separately. However, you cannot
deliver them before the object that they apply to exists.
Effective Dates
When you load translated values for an existing object, you must ensure that the effective dates in the translation
files are the same as those in the base-language version of the object. If you later update the object, then you
update the base-language object before updating the translation object. All components of a translated object must
remain synchronized.
Example: Job.dat
METADATA|Job|SourceSystemOwner|SourceSystemId|EffectiveStartDate|EffectiveEndDa
te|JobCode|Name|ActiveStatus
MERGE|Job|EBS-UK|JB2ACC44|2010/01/01|2014/04/04|ACADM|Accounts Administrator|A
MERGE|JOB|EBS-UK|JB2ACC44|2014/04/05|4712/12/31|ACADM|Accounts Clerk|A
Example: JobTranslation.dat
METADATA|Job|SourceSystemOwner|SourceSystemId|EffectiveStartDate|EffectiveEndDate
|Language|Name
MERGE|Job|EBS-UK|JB2ACC44|2010/01/01|2014/04/04|ES| Administrador de Cuentas
MERGE|JOB|EBS-UK|JB2ACC44|2014/04/05|4712/12/31|ES| Cuentas Clerk
If providing an updated translated value for a date-effective object and no date-effective split exists on the start date
of the new translation value, then you must also update the base-language object. This requirement exists to
ensure that the effective dates of the base-language and translation objects remain the same.
METADATA|JobFamily|EffectiveStartDate|EffectiveEndDate|JobFamilyName
DELETE|JobFamily|2012/10/01|4712/12/31|Sales01
Caution: Deleted data cannot be recovered. It is recommended that you try and correct your data rather than delete
and recreate it.
Before deleting an object, ensure that other business objects do not refer to it.
You can delete complete business objects and individual complete business-object components. You cannot
delete individual date-effective records.
When you delete a parent object, its child objects and any translation objects are also deleted. For example, to
delete a grade and its child business objects, you create a DELETE instruction for the Grade discriminator. To
delete only a grade rate value child component, you create a DELETE instruction for the GradeRateValue
discriminator.
You cannot delete worker objects from the production environment, though you can delete some child
components of the worker object. For example, you can delete the person e-mail component of a worker object.
You cannot include DELETE instructions in translation data files.
Deletion means complete removal of the object from Oracle HCM Cloud. A deleted object cannot be recovered.
To delete a date-effective object referenced by user keys, the EffectiveStartDate and EffectiveEndDate
attributes are mandatory.
To delete a date-effective object using source keys, Oracle HCM Cloud GUID or surrogate ID the effective start
and end dates are not mandatory.
You must not supply a DELETE instruction for an object that has a MERGE instruction in the same file. HCM
Data Loader will not know in which order to process the two instructions.
How to deliver your zip file of data to the WebCenter Content server
How to import and load your data
How to monitor progress and correct any errors
Some processes to run after loading Worker and Hierarchy Tree data
Before attempting to load any data into Oracle HCM Cloud, review the Preparing the Oracle Human Capital
Management Cloud Environment section on page 14.
To deliver a zip file to the WebCenter Content server, you can use the Oracle HCM Cloud File Import and Export
interface or the WebCenter Content web service.
3. In the Upload File dialog box, click Browse to locate the file that you want to upload.
4. In the Account field of the Upload File dialog box, select hcm/dataloader/import.
5. Click Save and Close.
WebCenter Content allocates a unique content ID to every file. To view the content ID allocated to your file, select
View - Columns - Content ID in the Search Results section of the File import and Export page. The row for your file
in the search results now includes the files content ID.
The Automating HCM Data Loader whitepaper explains how to use the WebCenter Content server web service.
This is available from the MOS document, HCM Data Loader: User Guide (Doc ID 1664133.1).
3. In the WebCenter Content Files dialog box, any files that have not been processed are listed. You can filter
the list to reduce it. For example, you can enter the WebCenter Content ID or file creation date. Select the file
that you posted to the WebCenter Content server and click Submit.
5. Click OK to close the message and return to the Import and Load Data page.
Parameter Description
File Name The name of the file on the WebCenter Content server to process.
Content ID WebCenter Content ID for the file on the WebCenter Content server.
Delete Source File Purge the source file from the WebCenter Content server after processing.
Maximum Percentage of Percentage of file lines in error that can occur in a business object before the import process stops for the
Import Errors object.
Maximum Percentage of Load Percentage of business-object instances in error that can occur for a business object before the load
Errors process stops.
Maximum Concurrent Threads The maximum number of concurrent process threads to use for loading your data set.
for Load
Load Group Size The number of objects to process at a time by each thread. The record counts will only be updated at the
end of processing each group.
Import Only
If you set the File Action parameter to Import only your business object data will be:
Streamed from your zip file on the WebCenter Content server, decrypting the stream if your file is encrypted
Validated for business object file name and METADATA definitions
Imported into the HCM Data Loader file line stage tables
Validated against attribute data types
Grouped by local key values to form logical records of related date-effective file lines. For example, all date-
effective file lines supplied for a job will be grouped into a logical occurrence of a job, such as the job
Accountant
Formed into logical objects by resolving parent references. For example the logical record for a valid grade will
be associated with the job it references
For more information on how to supply key values correctly, see the Supplying Key Values section on page 23.
Your valid logical objects will not be loaded into Oracle HCM Cloud if you submit your file in Import Only mode.
Import and Load
If you set the File Action parameter to Import and load, the above Import steps will be performed before valid
logical objects are submitted for loading. HCM Data Loader does not load your data directly into Oracle HCM Cloud,
it passes your valid object data to the business object specific services. These services are responsible for
performing validation that is specific to that business object.
1. Select the business object you wish to initiate Load for and click Load. Only business objects with a Loaded
status of Ready ( ), Error ( ), or Cancelled ( ) will have the Load button enabled.
2. On the ESS submission page, review the parameter values, update if necessary, and click Submit.
Monitoring Progress
The Search Results section presents one row for each data set. The Progress section of the search results is as
follows:
This section provides a summary of the import and load processes for each data set. If errors or warnings occur
during either the import or load process, then the relevant icons (warning and error ) appear. If both stages
complete successfully, then the green check mark ( ) appears in both columns.
Other icons that can be seen in the Progress section are In Progress ( ), Ready ( ), Locked ( ) and Cancelled
( ).
When warnings and errors occur, messages provide the details. You click the Messages icon to open the Messages
page.
The Imported Physical Rows section shows the percentage of rows in the data set imported successfully to the
stage tables. It also shows the total number of rows in the data set, the number of rows imported, and the number
that failed to import.
The Objects section shows the percentage of objects in the data set that loaded successfully to the application
tables. It also shows the total number of objects in the data set, the number of objects that are ready to load, the
number that loaded successfully, and the number that failed to load. As objects are created during the Import stage,
it is possible to see failed objects during import, before load has started.
Positive numbers in Failed columns are hyperlinks to more information about the failures.
For any data set selected in the Search Results section, the Business Objects tab in the Details section of the Import
and Load page provides information about the progress of each business object. For example, if the data set
includes both grades and locations, then one row appears for grades and one for locations.
The Processes tab in the Details section of the Import and Load page shows the status of the process submitted to
import and load the data set.
In the File Structure section of the page, expand any folders to see file lines with import errors. For example:
The Messages section of the File Line Errors page displays the associated error message.
The Details section of the File Line Errors page displays the contents of the physical row.
The Physical Row tab displays the METADATA and data lines supplied in the file for the record that has
errored:
Using this information, you can determine how to correct the import errors. You must import and load the corrected
data again, and you must add the corrected data file to a new zip file. Any attempt to process the existing zip file
again will fail.
In the File Structure section of the page, expand any folders to see objects with errors. When you select an object
with errors, the Details section of the Object Errors page shows the:
Object attributes and the values that you supplied for those attributes
Source-system references, if any
Contents of the physical row
For example, Attributes:
The values displayed in the Source System References tab are those supplied in the METADATA and data lines in
your file for the SourceRef attributes. See page 35 for details on how to correctly provide values that are displayed in
the user interface.
The Messages section of the Object Errors page displays error messages for the selected object.
Using this information, you can determine how to correct the errors. You must import and load the corrected data
again, and you must add the corrected data file to a new zip file. Any attempt to process the existing zip file again
will fail.
1. Select the data set you wish to stop, Refresh the Data Sets table to ensure that the data set is still processing.
The availability of the Stop button is determined by the Imported and Loaded statuses of the data set. The
button is enabled only if either is In Progress ( ).
2. Click Stop.
1. Select the Business Object you wish to stop, it is worth refreshing the Business Objects table to ensure that the
Business Object is still processing. The availability of the Stop button is determined by the Imported and
Loaded statuses of the business object, only if either are In Progress ( ) is the button in enabled.
2. Click Stop.
Potential Errors
Sometimes it is not valid to request a stop, perhaps processing has already completed normally, there are no
processes to stop, or a stop has already been requested. For these situations a dialog box will display the reason
why the stop request will not be submitted.
When a Business Object is stopped the process where the stop occurred will have a stopped status:
You cannot restart the Import process for stopped or failed imports. You can restart stopped and failed Load
processes. For more information, see Initiating Load / Resubmitting Load on page 47.
Extracting Data
HCM Data Loader makes use of two outputs from HCM Extracts. Like all seeded HCM Extracts it is recommended
that you make a copy of the seeded extract and tailor it to suit your use case.
The delivered output is in XML making the extract machine readable, you can however create your own BI Publisher
formats based on this extract.
Worker Synchronize Person Records When you run the Synchronize Person Records process, changes to person
and assignment details that have occurred since the last data load are
communicated to consuming applications, such as Oracle HCM Cloud
Trading Community Model and Oracle Identity Management, in the Oracle
HCM Cloud environment.
Worker Update Person Search Several attributes of person, employment, and profile records are used as
Keywords person-search keywords. This process copies keyword values from the
originating records to the PER_KEYWORDS table, where they are indexed to
improve search performance. When you run the Update Person Search
Keywords process, the whole PER_KEYWORDS table is refreshed; therefore,
you are recommended to run the process at times of low activity to avoid
performance problems.
Submit this process with the After Batch Load parameter set to Yes.
Worker Optimize Person Search Optimizes the index of the person search keywords table. Recommended to
Keywords Index be run after the Update Person Search Keywords process.
Worker Refresh Manager Hierarchy For performance reasons, the complete manager hierarchy for each person is
extracted from live data tables and stored in a separate manager hierarchy
table, known as the denormalized manager hierarchy. It ensures that a
person's manager hierarchy is both easily accessible and up to date. The
Refresh Manager Hierarchy process populates the denormalized manager
hierarchy table with latest information after each data load.
Worker Send Personal Data for Updates several person-related changes and updates the corresponding OIM
Multiple Users to LDAP attributes. An update request is sent to OIM which in turn updates the LDAP.
Run this process only when you want user accounts to be created or updated.
Worker Autoprovision Roles for All This process provisions / deprovisions roles based on where the
Users Autoprovision box is enabled.
Name Format Apply Name Formats to Applies name formats, Display Name, List Name, Full Name, Order Name, to
Person Names denormalized person name data when a name format is modified or added.
Organization Tree Node / Tree Flattening Logic Tree data flattening that improves query performance against the hierarchical
Department Tree Node data, especially for hierarchical queries such as roll-up queries.
Organization Tree Node / Tree Audit Auditing tree-structure metadata verifies that it conforms to all rules and
Department Tree Node ensures data integrity. Running an audit allows you to view audit details and
messages, and to correct any validation errors that the audit detects.
The frequency of deleting stage table data depends upon the volume and frequency of your data loads. But during
data migration, you may want to consider deleting every large Data Set as you finish with it.
There are two ways to delete HCM Data Loader stage table data:
Delete an individual data set from the Import and Load Data page.
Delete multiple data sets using the Delete Stage Table Data page.
2. Use the Search criteria to identify which data sets you want to include in the search. By default, all data sets
created by the current user that have not been updated in over a month will be returned.
3. Identify the correct data sets to purge and click Schedule.
Figure 53: Schedule Delete HCM Data Loader Stage Table Data
Caution: Deleting stage table data is not reversible. Once you have purged a data set you will no longer be able to
report on it, or extract errors that were generated for it.
Best Practices
File Shape
When determining your file shape keep the following actions are recommended:
Only extract changed attribute values, along with a unique reference to the record being maintained.
Never include a DELETE and MERGE instruction for the same record in the same file. HCM Data Loader does
not guarantee in which order the file lines are processed.
HCM Data Loader validates every attribute name supplied in METADATA lines in your file. It will negatively impact
performance to include attributes that you do not intend to supply data for.
Data Migration
When creating business objects during data conversion, it is recommended that you deliver one object type per zip
file. For example, create one zip file for jobs, one for grades, one for workers, and so on. You must ensure that you
load individual zip files in the correct order and correct any errors before loading the next object to avoid data-
reference errors.
Set the HCM Data Loader date-effective maintenance mode to replace by supplying the SET
PURGE_FUTURE_CHANGES Y command at the top of your file.
Supply #NULL for attributes that should have null values when supplying history.
Understand and adhere to the date-effective rules. See the section Date Effective and MCPD Components
on page 26 for more details.
When loading large volumes of data it is recommended that you regularly purge the stage table data for Data Sets
that you no longer need to reference. For more information, see the section Maintaining Stage Table Data on page
55.
Ongoing Interfaces
When reporting incremental changes for ongoing interfaces:
Extract only the changed attribute values, along with a unique reference to the record being updated.
o Set the HCM Data Loader behavior to retain future dated records by supplying the SET
PURGE_FUTURE_CHANGES N at the top of your file.
Note: If you do not supply this command any future dated records in existence for your updated date
range will be purged.
o Supply the #RETAIN tag for the effective end date if you do not want to correct any future dated
records.
o Leave the effective end date null if you want a change to roll on until the end of time.
Note: Every attribute specified will be used to correct each record within the specified date-range, this
will include attributes such as ActionCode.
o Leave the effective sequence blank to ensure a new MCPD split is generated with the correct
sequence for a new multiple changes per day record (MCPD).
Supply all business object files in the same compressed zip file. HCM Data Loader ensures they are processed
in the correct order. Referenced data is loaded before the data that references it.
Additional Help
Report Output
The HCM Data Loader Data-Set Summary is a user readable HTML output that provides status information, along
with details of every ESS process submitted to process your data set.
For each business object included in your data set the business object status and file definition is reported. The
following sections are used to provide technical information about your failed records:
Parameters
It is advisable to restrict the report output to errors that need further investigation. The following parameters are
available to achieve this:
**Content ID A unique reference to a single Data Set Data Sets table Content ID
**Process ID A unique reference to a single Data Set Data Sets table Process ID
Business Object Name The name of a business object within the Data Set. This Business Objects table Business Object
is optional though it is recommended if your do not supply
the other parameter values.
Message Text Partial or complete message text. Only records that Messages page Message Text, or
failed with this message will be reported. Error Management page Message Text
User keys A comma delimited list of the user key value. Only Error Management Data Structure for Object
records with these user keys will be reported errors
Line Numbers A comma delimited list of file line numbers. Only the file Error Management Data Structure for Line errors.
lines with these sequence numbers will be reported.
Figure 54: Diagnostic Dashboard (Settings and Actions - Troubleshooting - Run Diagnostic Tests)
1. On the Diagnostic Dashboard (User Name Settings and Actions Troubleshooting List Run
Diagnostic Tests, search for the HCM Data Loader Data-Set Summary test by entering the name in the Test
Name search field and clicking Search.
2. Select the test by clicking the checkbox to the left of the test name and click Add to Run.
The HCM Data Loader Data-Set Summary appears in the Choose Tests to Run and Supply Inputs section.
Figure 56: Selecting the HCM Data Loader Data-Set Status diagnostic test
3. To review the parameter values, click the Click to Supply or Edit Input Parameters button.
4. Review the available parameters and provide values to target the output for the data you need to report.
5. Enter the parameter values and click OK.. The parameters window closes.
6. Enter a name in the Run Name field to name your test run. Alternatively, leave this field blank for the
application to generate a name.
8. Click OK in the confirmation dialog box displaying the test Run name.
9. Click the Display Latest Test Run Status Information link to retrieve the run results.
Figure 60: Reviewing the HCM Data Loader Data-Set Summary test run status
10. Expand the test hierarchy to see the HCM Data Loader Data-Set Status output and click on the Report icon to
open the report.
The output can be saved and attached to a service request if you need support from Oracle.
business object A data structure that represents a real-world business artifact, such as worker or job. Comprises one or more
business-object components in a hierarchical structure.
child component A component of a business object that occurs below the top level of the component hierarchy.
component A logical grouping of attributes in a business object. A component has a unique ID that enables it to be
maintained independently of the business object to which it belongs.
data set A zip file containing one or more .dat files to be loaded.
date-effective Records that store the history of a component. Date-effective components do not have any gaps in their
history. Examples of date-effective components are Job, Contract, Assignment Manager.
discriminator In an HCM Data Loader .dat file, the value that identifies the business-object component to be loaded.
file-line instruction tag In an HCM Data Loader .dat file, the value that identifies the purpose of a file line. Valid tags are: COMMENT,
DELETE, METADATA, MERGE, and SET.
file template The data (.dat) file supplied for each integration-enabled business object. It contains a METADATA file line for
each business-object component showing all attributes of the component. File templates are also supplied for
translation-object components.
integration-enabled object Business object that can be loaded using HCM Data Loader and for which a Logical Object interface method
exists.
logical object The grouping of related data lines to form one occurrence of the object, such as the Job Sales Consultant.
MCPD Some date-effective components support reporting Multiple Changes Per Day (MCPD). These allow different
attribute values on the same record to be changed and stored as separate updates, this is achieved by having
an effective sequence for each change on the same effective start date. Examples of MCPD components are
Work Terms and Assignment.
METADATA file line In an HCM Data Loader .dat file, the file-instruction line that defines, for a business-object component, the
attributes to be loaded and their order.
parent component A component of a business object that occurs at the top of the component hierarchy.
primary key A key made up of the attributes that uniquely identify a row.
simple-dated Components that have a date range during which they are valid, typically date from and date to. These
components can have gaps in the date records, unlike date-effective components. Examples of simple dated
components are Person Address, Person Email.
source key The combination of a source system identifier and name used to uniquely refefence a record.
source-system reference Source system table name, column name, and attribute values optionally included in a business-object
component to be loaded.
user key A key formed of real-world attributes, such as person name or job code and job set code.
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
warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
facebook.com/oracle fitness for a particular purpose. We specifically disclaim any liability with respect to this document, and no contractual obligations are
formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any
twitter.com/oracle means, electronic or mechanical, for any purpose, without our prior written permission.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
oracle.com
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. 0915