Integrating With HCM

November 24, 2022 | Author: Anonymous | Category: N/A

Short Description

Download Integrating With HCM...

Description

Oracle Human Capital Management Cloud Integrating with HCM

19A

Oracle Human Capital Management Cloud Integrating with HCM 19A Part Number F11181-02 Copyright © 2011-2019, Oracle and/or its affiliates. All rights reserved. Authors: Suzanne Suzanne Kinkead, Alison Firth, Susan Susan Saha, Lakshmi Venkat This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/ or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. 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 Micro Devices. UNIX UNIX is a registered registered trademark of The Open Group. Group. This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle. The business names names used in this documenta documentation tion are fictitiou fictitious, s, and are not intended to ident identify ify any real com companies panies current currently ly or previously in existence existence..

Oracle Human Capital Management Cloud

Integrating with HCM

Contents Preface

1

i

Introduction to Integrating with Oracle HCM Cloud Integrating with Oracle HCM Cloud: Overview

.......................................................................................................... 1

................................................................................................................................ 6

Inbound Integrations: Explained Outbound Integrations: Explained

2

1

.............................................................................................................................

7

Introduction to HCM Data Loader

9

HCM Data Loader: Overview

9

....................................................................................................................................

HCM Data Loader and Implementation Scenarios: Overview .................................................................................. 10 HCM Data Loader Process: Explained .................................................................................................................... 11 Supported Key Types: Explained Source Keys: Explained User Keys: Explained

............................................................................................................................ 12

..........................................................................................................................................

13

..............................................................................................................................................

14

Oracle Fusion GUIDs and Surrogate IDs: Explained

............................ .. ......................................................................................... ....................................................................................... 15

Business-Object Business-Obj ect Structure: Explained

FAQs for Introduction Introduction to HCM Data Loader

3

................................................................................................ 15

.................................................................................. ................................................................................ 17 .......................... ..

Data File Instructions and Delivery

19

HCM Data Loader Data and .zip Files: Explained .................................................................................................... 19 File Line Instructions and File Discriminators: Explained .......................................................................................... 20 The METADATA Instruction: Explained

.................................................................................................................... 22

The MERGE Instruction: Explained

.........................................................................................................................

The DELETE Instruction: Explained

......................................................................................................................... 24

The SET Instruction

................................................................................................................................................

Generating and Using Template Files: Procedure FAQs for Data File Data File Instructions and Delivery

22 24

.................................................................................................... 27

.................... ....................................................................................... 29 .................. .........................................................................................

Oracle Human Capital Management Cloud

Integrating with HCM

4

Preparing to Use HCM Data Loader

31

Finding Business-Object Information: Explained ...................................................................................................... 31 HCM Data Loader Configuration Parameters HCM Data Loader Scope: Explained

.......................................................................................................... 32

...................................................................................................................... 37

Defining Referenced Objects: Explained

.................................................................................................................. 39

Reviewing Lists of Values: Explained ....................................................................................................................... 40 Defining the Source-System Owner: Procedure ...................................................................................................... 41 Preparing to Load Workers: Points to Consider

...................................................................................................... 41

Testing the HCM Data Loader Process Flow and Connections: Explained .............................................................. 43 Auditing Objects Loaded in Bulk: Explained ............................................................................................................ 44 FAQs for Preparing to Use HCM Data Loader

5

........................................................................................................ 45

Data Preparation

47

Preparing the Source Data: Points to Consider

....................................................................................................... 47

General Data Considerations for HCM Data Loader: Explained

............................................................................... 47

Loading Images, Attachments, and Large Strings: Explained .................................................................................. 49 Supplying Source-Key Values: Points to Consider .................................................................................................. 50 Updating Source Keys: Explained

........................................................................................................................... 51

Supplying User-Key Values: Points to Consider

...................................................................................................... 52

Supplying Oracle Fusion Surrogate IDs: Examples Supplying Oracle Fusion GUIDs: Examples

.................................................................................................. 52

............................................................................................................. 53

Managing Reserved Characters: Explained ............................................................................................................. 54 Loading and Maintaining Translated Objects: Explained .......................................................................................... 55 Including Source-System References in Data Files: Explained ................................................................................. 56 Deleting Data Using HCM Data Loader: Explained

6

.................................................................................................. 57

Loading Date-Effective Data Loading Date-Effective Objects: Overview

59 ............................................................................................................... 59

Loading Objects with Multiple Changes Per Day: Explained

.................................................................................... 60

Updating Date-Effective Objects That Have Future-Dated Records: Explained ........................................................ 62 Retaining Attribute Values in Future-Dated Records: Examples ............................................................................... 63 Carrying Forward Changed Attribute Values in Retain Mode: Points to Consider ..................................................... 65 Using Replace Mode to Update an Assignment: Examples ..................................................................................... 66 Changing First Effective Start Date and Last Effective End Date: Examples ............................................................. 68

Oracle Human Capital Management Cloud

Integrating with HCM

7

Loading Flexfield Data Loading Flexfield Data: Explained

8

71 ............................................................................................................................ 71

Loading Data for Descriptive Flexfields: Explained

................................................................................................... 72

Loading Data for Descriptive Flexfields: Examples

................................................................................................... 73

Loading Data for Extensible Flexfields: Explained

.................................................................................................... 74

Loading Data for Extensible Flexfields: Examples

.................................................................................................... 75

Loading Setup Objects

77

Loading Absence Cases: Explained

........................................................................................................................ 77

Loading Actions: Examples

..................................................................................................................................... 77

Loading Action Reasons: Examples

........................................................................................................................ 78

Loading Calendar Events: Explained

....................................................................................................................... 79

Loading Checklist Templates: Explained

................................................................................................................. 80

Loading Checklist Templates: Examples

................................................................................................................. 81

Loading Document Delivery Preferences: Explained Loading Document Types: Explained Loading Document Types: Examples

................................................................................................ 83

...................................................................................................................... 84 ...................................................................................................................... 85

Loading Extended Lookup Codes: Examples

.......................................................................................................... 87

Loading Name Formats: Explained

......................................................................................................................... 88

Loading Person Types: Examples

........................................................................................................................... 90

Loading Resource Exceptions: Examples

................................................................................................................ 91

Loading Time and Labor Event Groups: Examples

................................................................................................. 92

Loading Time and Labor Event Groups: Explained

................................................................................................. 93

Columns and Event Source Objects for Time and Labor Events Loading Time and Time and Labor Event Actions: Examples

............................................................................. 94

...................................... ... ........................................................... ........................................................ 96

Oracle Human Capital Management Cloud

Integrating with HCM

9

Loading Workers Loading Workers: Overview

99 ....................................................................................................................................

Loading New Workers: Points to Consider

........................................................................................................... 100

Effective Start and End Dates for Worker Components: Explained Deleting Worker Components: Explained

99

........................................................................ 102

.............................................................................................................. 103

Checking for Duplicate Person Records: Explained ............................................................................................... 104 Person Numbers in Worker Objects: Explained ..................................................................................................... 105 Loading External Identifiers: I dentifiers: Explained

.................................................................................................................. 106

Loading Person Names: Points to Consider Loading Person Images: Explained

......................................................................................................... 107

....................................................................................................................... 108

Work Relationship Changes: Examples

................................................................................................................. 108

Performing a Global Transfer: Explained

............................................................................................................... 110

Loading Additional Assignments: Explained .......................................................................................................... 111 Loading Temporary Assignments: Explained

......................................................................................................... 112

Loading Person Legislative Data: Explained

.......................................................................................................... 113

Loading Employment Terms: Explained

................................................................................................................ 114

Automatic Calculation of FTE Values for Workers: Explained ................................................................................. 114 Creating Default Default Working-Hour Patterns: Explained

............................................................................................... 115

Loading Assignment Assignment Eligible Jobs: Examples

....................................... ... ................................................................. .............................................................. 115

Loading Seniority Seniority Dates: Points to Consider

.............. ............................................................................................. ........................................................................................... 117 ............

Loading Seniority Seniority Date Adjustments: Examples ..................................................................................................... ..................................................................................................... 118 Loading Seniority Seniority Hours: Examples

.................................... .. ................................................................................... ................................................................................. 120

Loading Contract Contract Extensions: Examples

....................................................................................... ..................................................................................... 121 ........................ ..

Loading Default Default Expense Accounts for Workers: Examples ................................................................................... 122 FAQs for Loading Loading Workers

........................ ....................... ....................... .................... .......... ............................................................................ .......................................................................... 123 ............

Oracle Human Capital Management Cloud

Integrating with HCM

10

Loading Worker-Related Objects Loading Allocated Checklists: Example

125

................................................................................................................. 125

Loading Areas of Responsibility: Explained

........................................................................................................... 125

Loading Document Records: Explained ................................................................................................................ 126 .............................................................................................................. 128

Loading Time Record Groups: Explained

Loading Time Record Groups: Examples .............................................................................................................. 129 Loading User-Update Requests: Explained ........................................................................................................... 130 Loading User-Update Requests: Examples Loading Worker Schedules: Explained

.................................................................................................................. 133

Creating Worker Schedules: Examples

................................................................................................................. 135

Updating Worker Worker Schedules: Examples

..................................................................................... ................................................................................... 136 ........................... ..

FAQs for Loading Loading Worker-Related Objects

11

........................................................................................................... 131

...................... ........................ ..................................................................................... ................................................................................... 137

Loading Work Structures Loading Work Structures: Overview

139

...................................................................................................................... 139

Loading Collective Agreements: Explained ............................................................................................................ 140 Loading Grades: Explained ................................................................................................................................... 141 Loading Grade Ladders: Explained Loading Grade Rates: Explained Loading Jobs: Explained

....................................................................................................................... 142 ........................................................................................................................... 143

....................................................................................................................................... 143

Loading Job Families: Examples Loading Locations: Explained

...............................................................................................................................

145

.........................................................................................................................

145

Loading Organizations: Explained Loading Positions: Positions: Explained

........................................................................................................................... 144

....................... ....................... .................... .......... ..................................................................................... ................................................................................... 147 ............

Loading HCM Position HCM Position Hierarchies: Examples

................... ...................................................................................... .................................................................................... 148 .................

Loading Department Department Trees: Explained ................... .. ............................................................................................... ............................................................................................. 150 ....................................................................................... ..................................................................................... 151 Loading Department Department Tree Nodes: Explained .................. .. Loading Department Department Tree Nodes: Examples Loading Organization Organization Trees: Explained

......................................................................................................... .................... ..................................................................................... 152

................... ................................................................................................ .............................................................................................. 155 .................

Loading Organization Organization Tree Nodes: Explained

..................... ..................................................................................... ................................................................................... 156 ...................

Loading Organization Organization Tree Nodes: Exampl Examples es   ........................................................................................................ 157

Oracle Human Capital Management Cloud

Integrating with HCM

12

Loading Compensation Objects

161

Loading Progression Grade Ladders: Explained .................................................................................................... 161 Loading Progression Grade Ladders with Steps: Examples

.................................................................................. 162

Loading Progression Grade Ladders Without Steps: Examples ............................................................................. 165 Loading Progression Grade Rates: Explained

....................................................................................................... 166

Loading Progression Grade Rates: Examples ....................................................................................................... 167 Loading Progression Rules: Explained .................................................................................................................. 168 Loading Progression Rules: Examples

.................................................................................................................. 169

Loading Salary Basis Records: Points to Consider

............................................................................................... 170

Loading Salary Records: Explained

....................................................................................................................... 172

Loading Salary Records: Examples

....................................................................................................................... 173

Loading Salary Range Differential Profiles and Values: Examples .......................................................................... 175 Making Date-Effective Changes to Salary Range Differentials: Explained ............................................................... 176

13

Loading Global Payroll Objects

179

Loading Legislative Data Groups: Examples ......................................................................................................... 179 Loading Banks ...................................................................................................................................................... 179 Loading Calculation Cards: Explained Loading Fast Formulas

................................................................................................................... 181

.........................................................................................................................................

183

Loading Payroll Balance Definitions: Explained ...................................................................................................... 184 Loading Payroll Definitions

....................................................................................................................................

187

Loading Payroll Element Definitions: Explained ...................................................................................................... 191 Loading Payroll Element Run Usage: Explained Loading Payment Methods

...................................................................................................................................

Loading Payroll Balance Groups Loading Payroll Time Cards

.................................................................................................... 193 194

........................................................................................................................... 198

.................................................................................................................................. 204

Oracle Human Capital Management Cloud

Integrating with HCM

14

Loading Talent Objects

207

Loading Goals, Goal Plans, and Goal Plan Sets: Overview

................................................................................... 207

Loading Goals: Explained

.....................................................................................................................................

207

Loading Goals: Examples

.....................................................................................................................................

210

Loading Goal Plans: Explained

.............................................................................................................................. 211

Loading Goal Plans: Examples ............................................................................................................................. 212 Loading Goal Plan Sets: Explained ....................................................................................................................... 213 Loading Goal Plan Sets: Examples

....................................................................................................................... 214

Loading Mass Actions for Performance Documents: Examples ............................................................................. 215 Loading Succession Plans: Examples Loading Talent Pools: Examples

................................................................................................................... 217

........................................................................................................................... 218

Loading Talent Profile Data: Explained

.................................................................................................................. 219

Loading Talent Review Meetings: Examples FAQs for Loading Talent Objects

15

.......................................................................................................... 221

.......................................................................................................................... 223

Loading Learning Objects

225

Loading Classroom Resources: Examples ............................................................................................................ 225 Loading Course Offering Pricing Defaults: Examples

............................................................................................. 225

Loading Courses: Explained

.................................................................................................................................. 226

Loading Courses: Examples

.................................................................................................................................

227

Loading Learning Record Activity Attempts: Example ........................................................................................... 228 Loading Legacy Learning Items: Examples

........................................................................................................... 228

Loading Offering Custom Pricing Objects: Examples Loading Specializations: Examples

16

............................................................................................ 229

........................................................................................................................ 230

Loading Absences Topics

233

Loading Accrual Plan Enrollments: Explained ........................................................................................................ 233 Loading Absence Qualification Plan Entitlement: Explained ................................................................................... 233 Loading Absence Entry: Explained

........................................................................................................................ 234

Loading Absence Entry: Examples

........................................................................................................................ 234

Oracle Human Capital Management Cloud

Integrating with HCM

17

Loading Benefits Objects

237

Loading Beneficiary Enrollment: Explained

............................................................................................................ 237

Loading Dependent Enrollment: Explained ............................................................................................................ 238 Loading Participant Enrollment: Explained

............................................................................................................. 239

Loading Person Benefit Group: Explained

............................................................................................................. 240

Loading Person Benefit Balance: Explained .......................................................................................................... 241 Loading Person Habits: Explained ........................................................................................................................ 241

18

Importing and Loading Data Using HCM Data Loader Importing and Loading Data: Points to Consider

................................................................................................... 243

............................................................................................................... 244

Importing and Loading Data: Procedure Import and Load Data Search Results

243

.................................................................................................................. 246

Uploading Data Using HCM Data Loader: Worked Example ................................................................................. 248 Reviewing and Correcting Errors: Procedure

......................................................................................................... 250

Stopping HCM Data Loader Processing: Procedure

............................................................................................. 252

Automating Data Loading: Overview ..................................................................................................................... 252 FAQs for Importing and Loading Data Using HCM Data Loader ............................................................................ 253

19

Data Loading Using Spreadsheets Spreadsheet Data Loaders: Explained

257

.................................................................................................................. 257

Setting Up the Desktop Integration for Excel: Procedure

...................................................................................... 258

Troubleshooting the Desktop Integration for Excel: Procedure .............................................................................. 259

20

Introduction to HCM Spreadsheet Data Loader

261

Using HCM Spreadsheet Data Loader: Points to Consider ................................................................................... 261 Uploading Data Using HCM Spreadsheet Data Loader: How It's Processed ......................................................... 262 Testing the HCM Spreadsheet Spreadsheet Data Loader Process Flow and Connections: Connections: Explained ........................................ 264 Managing Spreadsheet Business Object Access: Explained

.................................................................................. 265

Managing Spreadsheet Business Object Access: Procedure

................................................................................ 266

Access to HCM Spreadsheet Data Loader Tasks: Explained ................................................................................ 268 FAQs for HCM Spreadsheet Data Loader

............................................................................................................. 269

Oracle Human Capital Management Cloud

Integrating with HCM

21

HCM Spreadsheet Data Loader Templates HCM Spreadsheet Data Loader Templates: Explained

271

.......................................................................................... 271

Defining Categories for Spreadshee Spreadsheett Templates: Procedure .................................................................................. 273 Creating and Editing Spreadsheet Templates: Procedure ...................................................................................... 273 Template Security: Explained

................................................................................................................................ 276

Setting Spreadsheet Template Parameters: Procedure ......................................................................................... 277 Designing Spreadsheet Templates: Explained ....................................................................................................... 278 Designing Spreadsheet Templates: Templates: Points to Consider

......................................................................................... 280

............................................ .......................................... 281 Configuring Default Default Values for Spreadshee Spreadsheett Attributes: Explained .............................. .. ........................ ....................... ....................... ........................ .................. ...... 282 282 Configuring Lists Lists of Values for Attribute Validation: Procedure .............. ............ .............. Autogenerated Autogenerate d Attribute Values in Spreadshee Spreadsheett Templates: Explained ................................................................... 284 Copying Spreadsheet Templates: Procedure ........................................................................................................ 285 Exporting and Importing I mporting Spreadsheet Templates: Procedure ................................................................................ 285 FAQs for HCM Spreadsheet Data Loader Templates

22

............................................................................................ 286

Importing and Loading Data Using HCM Spreadsheet Data Loader Generating Spreadsheets: Procedure

289

.................................................................................................................... 289

Importing Data to a Spreadsheet: Procedure

........................................................................................................ 289

Managing Spreadsheet Data Sets: Procedure

....................................................................................................... 290

Uploading Data: Worked Example

........................................................................................................................ 292

Deleting Data Using HCM Spreadsheet Data Loader: Explained ........................................................................... 294 FAQs for Importing and Loading Data Using HCM Spreadsheet Data Loader ............ ........................ ....................... ....................... .................... ........ 294

23

Postload Processing

297

Processes to Run After Loading Data

................................................................................................................... 297

Running Postload Processes: Points to Consider Validating Loaded Data: Explained

24

................................................................................................. 299

........................................................................................................................ 300

Purging Person Data from Test Environments

303

Purging Person Data from Test Environments: Explained

...................................................................................... 303

Purging Person Data from Test Environments: Procedure

..................................................................................... 304

Tables Purged by the Purge Person Data in Test Environments Process .............................................................. 305

Oracle Human Capital Management Cloud

Integrating with HCM

25

HCM Extracts and Diagnostics for HCM Data Loader and HCM Spreadsheet Data Loader

311

HCM Data Loader Extracts: Explained

.................................................................................................................. 311

Setting Up HCM Data Loader Extracts

................................................................................................................. 311

Running HCM Data Loader Extracts

..................................................................................................................... 316

Diagnostic Tests for HCM Data Loader ................................................................................................................ 319 Diagnostic Tests for HCM Spreadsheet Data Loader ............................................................................................ 320

26

Best Practice Practices s for HCM HCM Data Data Loader Loader and HCM HCM Spreadshe Spreadsheet et Data Loader 323 HCM Data Loader Best Practices: Points to Consider Maintaining the Stage Tables: Overview

.......................................................................................... 323

................................................................................................................ 324

Automatic Deletion and Backup of Stage Table Data: Example ............................................................................. 326 Maintaining the HCM Data Loader Stage Tables: Procedure

................................................................................. 328

Maintaining the HCM Spreadsheet Data Loader Stage Tables: Procedure ............................................................ 330

27

Payroll Data Loading

333

Overview

333

...............................................................................................................................................................

Initial Balance Loading: Explained

......................................................................................................................... 334 ................................................................................................................... 335

Initial Balances: How They're Loaded Balance Batch Header and Lines Views

............................................................................................................... 337

Adjusting Multiple Balances: Procedure

................................................................................................................ 339

..................................................................................................................... 339

Adjusting Balances: Critical Choices Adjusting Balances: Worked Example

28

................................................................................................................... 344

Payroll Batch Loader

347

Overview

347

...............................................................................................................................................................

Importing Data: Procedure

.................................................................................................................................... 351

Configuring a Report to View Batch Line Errors: Worked Example ........................................................................ 352 Task Actions for Migrating Elements: Explained .................................................................................................... 357 Migrating Objects: Procedure FAQs for Payroll Batch Loader

29

................................................................................................................................ 360 .............................................................................................................................

Payroll Batch Loader Using Workbooks Payroll Batch Statuses: Explained

360

363

......................................................................................................................... 363

Creating Element Entries Using the Batch Loader: Worked Example ..................................................................... 363 Creating Globals Using the Batch Loader: Worked Example FAQs for Payroll Batch Loader Using Workbooks

................................................................................. 366

................................................................................................. 368

Oracle Human Capital Management Cloud

Integrating with HCM

30

Payroll Batch Loader File Loading

371

Overview

371

...............................................................................................................................................................

Automating Payroll Data Loads: Procedure

........................................................................................................... 373

File Format and Data Transformation for Payroll Batch Uploads: Critical Choices .................................................. 376 Batch Loader Formula Type

.................................................................................................................................

377

Sample Formula for Batch Loader File Transformation .......................................................................................... 379 Sample Batch Loader Formula for Multiple Tasks ................................................................................................. 380

31

Payroll Batch Loader Workbooks

383

Payroll Batch Loader Workbook for Balance Adjustments ..................................................................................... 383 Payroll Batch Loader Workbook for Costing Setups Payroll Batch Loader Workbook for Elements

............................................................................................. 385

....................................................................................................... 391 ......................................................................................... 403

Payroll Batch Loader Workbook for Payment Methods Payroll Batch Loader Workbook for Payroll Relationships

...................................................................................... 411

Payroll Batch Loader Workbook for Third-Party Organizations .............................................................................. 417 Payroll Batch Loader Workbook for User-Defined Tables

32

...................................................................................... 421

Time, Absence, and Pension Data for Payroll

437

Overview

437

...............................................................................................................................................................

Prerequisite Payroll Setup for Importing Time Entries: Explained Creating Elements for Time Card Entries: Procedure Importing Time Card Entries to Payroll: Procedure File Format for Importing Time Entries

........................................................................... 438

............................................................................................ 440 ................................................................................................ 443

.................................................................................................................. 445

Integrating Absence Management with Global Payroll: Procedure ......................................................................... 447 Defining Payroll Elements for Processing Absences: Procedure ............................................................................ 449 Importing Absence Entries to Payroll: Procedure File Format for Importing Absence Entries

.................................................................................................. 452

............................................................................................................ 454

Running the Load Benefit Batches Process: Procedure File Format for Importing Pension Deductions

........................................................................................ 457

....................................................................................................... 458

Oracle Human Capital Management Cloud

Integrating with HCM

33

Managing HCM Extracts

461

Extract Components: How They Work Together

................................................................................................... 461

.............................................................................................................................

HCM Extract Types: Explained

Payroll Interface Extract Definitions: Overview

462

....................................................................................................... 463

................................................................................................................... 464

Viewing User Entity Details: Explained

Frequently Used User Entities ............................................................................................................................... 465 HCM Extracts Templates: Explained ..................................................................................................................... 466 Defining an Extract: Worked Example

................................................................................................................... 467 ................................................................................................... 473

Using the Simplified Interface: Worked Example

......................................................................................................................... 478

Validating Extracts: How It Works

Viewing Extract Run Details: Explained ................................................................................................................. 479 FAQs for Managing Extracts

34

................................................................................................................................. 480

Filtering and Delivering HCM Extracts

483

Using Extract Modes: Explained

483

...........................................................................................................................

Filtering Extracts Using Advanced Filter Criteria: Example ..................................................................................... 484 HCM Extract Formula Types ................................................................................................................................. 485 Delivery Options: Explained

................................................................................................................................... 485

Defining the BI Publisher Template: Worked Example

........................................................................................... 486

Delivering Encrypted Data Using HCM Extracts: Explained FAQs for Filtering and Delivering HCM Extracts

35

................................................................................... 488

.................................................................................................... 488

Flow Patterns

493

Flow Patterns for Extracts and Reports: Overview

.................................................................................................................... 493

Checklist and Flow Tasks: Explained Editing Flow Tasks: Points to Consider Flow Pattern Parameters: Explained

................................................................................................................. 493

...................................................................................................................... 494

Flow Task Start and Due Dates: Critical Choices Editing Flow Patterns: Examples

................................................................................................ 493

.................................................................................................. 498

........................................................................................................................... 499

Adding a BI Publisher Report to a Flow: Procedure .............................................................................................. 502 Creating a Flow within a Flow: Worked Example FAQs for Flow Patterns

.................................................................................................. 503

......................................................................................................................................... 505

Oracle Human Capital Management Cloud

Integrating with HCM

36

Benefits Data Extract

509

Extracting Benefits Data Using HCM Extracts: Points to Consider Configuring for Plan Carriers: Procedure Valid Extract Names: Explained

........................................................................ 509

............................................................................................................... 509

............................................................................................................................

512

Generating and Transmitting Extracts: Procedure ................................................................................................. 513 Custom Layout

37

.....................................................................................................................................................

Talent Review and Succession Management Data Extract Extract Talent Review Data Using HCM Extracts

................................................................................. 522

Transferring Encrypted Data Setting up Encryption for File Transfer: Procedure

521

.................................................................................................. 521

Extract Succession Management Data Using HCM Extracts

38

514

525 ................................................................................................ 525

Encrypting and Uploading Files Automatically: Procedure ..................................................................................... 527 Transferring Files Automatically Automatically from HCM Extracts with PGP Encryption: Procedure ............................................ 528

39

Oracle Taleo Recruiting Cloud Service Integration

531

HCM and Oracle Taleo Recruiting Cloud Service Components: How They Work Together .................................... 531 ....................... ....................... .................. ...... 531 531 Importing Data From Oracle Taleo Recruiting Cloud Service: Explained ........................ .................................... ....................... ....................... ...................... .......... 532 Exporting Data to Oracle Taleo Recruiting Cloud Service: Explained ........................ .................................... FAQs for Oracle Taleo Recruiting Cloud Service and HCM Integration

40

.................................................................. 534

Web Services

535

Overview

535

...............................................................................................................................................................

Oracle Human Capital Management Cloud

Integrating with HCM

Oracle Human Capital Management Cloud

Preface

Integrating with HCM

Preface This preface introduces information information sources th that at can help you use the application. application.

Using Oracle Applications Using Applications Help

Use help iicons cons to acc access ess h help elp in the a application. pplication. If you don't see any any help icons on your page, page, click click your user image image or name in the global header and select Show Help Icons. Not all pages have help icons. You can also access Oracle Applications Help. Watch: This video tutorial shows you how to find help and use help features.

You can also read Using Applications Help.

Additional Resources • Community: Use Oracle Cloud Customer Connect to get information from experts at Oracle, the partner partner community, and other users. videos. • Guides and Videos: Go to the Oracle Help Center to find guides and videos. • Training: Take courses on Oracle Cloud from Oracle University.

Conventions The following table table explain explainss the text con conventions ventions used in this guide. guide. Convention

Meaning

boldface

Boldface type indicates user interface elements, navigation paths, or values you enter or select.

monospace

Monospace type indicates file, folder, and directory names, code examples, commands, and URLs.

>

Greater than symbol separates elements in a navigation path.

Documentation Accessibility For information about Oracle's commitment to accessibi accessibility, lity, visit the Oracle Accessibility Program website. Videos included included in this guide are provid provided ed as a m media edia alternative alternative for text-based text-based help top topics ics also available available in thi thiss guide.

i

Oracle Human Capital Management Cloud

Preface

Integrating with HCM

Contacting Oracle Access to Oracle Support Oracle customers that have purchased support have access to electronic support through My Oracle Support. For Oracle Support if you are hearing impaired. information, visit My Oracle Support or visit Accessible Oracle

Comments and Suggestions Please give us feedback about Oracle Applications Help and guides! You can send an e-mail to: oracle_fusion_applications_he oracle_fusion_ap plications_help_ww_grp@oracle [email protected]. .com.

ii

Oracle Human Capital Management Cloud

Chapter 1

Integrating with HCM

Introduction to Integrating with Oracle HCM Cloud

1 Introduction to Integrating with Oracle HCM Cloud Integrating with Oracle HCM Cloud: Overview This guide describes describes the ways in whic which h you can inte integrate grate applications applications with Orac Oracle le HCM Cloud. Most Most of the content content describes ways of loading or extracting data. This topic shows shows the scope of this guide and summarizes summarizes the contents of each chapter. chapter.

Introduction This table describes describes chapter chapter 1. Chapter

Title

Contents

1

Introduction to Integrating with Oracle HCM Cloud

An introduction to this guide and an overvie overview w of the available approaches to data loading and extracts.

Data Loading Using HCM Data Loader This table describes describes chapters chapters 2 through 18. Chapter

Title

Contents

2

Introduction to HCM Data Loader

An introduction to HCM Dat Data a Loader and th the e data-loading process.

3

Data File Instructions and Delivery

Valid instructions instructions to include in data files, how to deliver data files for upload, and how to generate and use business-object templates.

4

Preparing to Use HCM Data Loader

Setting configuration parameters, defining referenced objects, reviewing lists of values, and finding business-object information.

5

Data Preparation

General guidance for preparing various types of data, such as images and attachments attachments,, to ensure successful loading. Information about specifying the supported key types.

1

Oracle Human Capital Management Cloud

Chapter 1

Integrating with HCM

Introduction to Integrating with Oracle HCM Cloud

Chapter

Title

Contents

6

Loading Date-Effective Data

How to load date-effective objects successfully and achieve the required results.

7

Loading Flexfield Data

How to load data for descriptive and extensible flexfields.

8

Loading Setup Objects

How to load setup objects, such as Actions, Action Reasons, Reasons, Name For Format, mat, and Per Person son Type.

9

Loading Workers

How to load components of the Worker object.

10

Loading Worker-Related Objects

How to load worker-related objects, such as Area of Responsibility, Responsibility, Docum Document ent Record, and User.

11

Loading Work Structures

How to load work structures, such as Grade, Job, and Organization.

12

Loading Compensation Objects

How to load Grade compensation such and as Progression Ladder, objects, Salary Basis, Salary.

13

Loading Global Payroll Objects

How to load payroll objects, such as Calculation Card, Bank, Fast Formula, and Payroll Consolidation Group.

14

Loading Talent Objects

How to load talent objects, such as Goal and Goal Plan.

15

Loading Learning Objects

How to load learning objects, such as Course, Classroom Resource, and Legacy Learning Item.

16

Loading Absences Objects

How to load absences objects, such as Accrual Plan Enrollment and Absence Entry.

17

Loading Benefits Objects

How to load benefits objects, such as Beneficiary Enrollments, Person Benefit Groups, and Person Habits.

18

Importing and Loading Data Using HCM Data Loader

How to import and load data and correct any errors.

2

Oracle Human Capital Management Cloud

Chapter 1

Integrating with HCM

Introduction to Integrating with Oracle HCM Cloud

Data Loading Using Spreadsheet Loaders This table describes describes chapters chapters 19 through 22. Chapter

Title

Contents

19

Data Loading Using Spreadsheets

An overview of the available spreadsheet loaders and general setup requirements for spreadsheet usage.

20

Introduction to HCM Spreadsheet Data Loader

An overview of HCM Spreads Spreadsheet heet Data Loader, its processing, and its access requirements.

21

HCM Spreadsheet Data Loader Templates

How to create, edit, copy, export, and import spreadsheet templates.

22

Importing and Loading Data Using HCM Spreadsheet Data Loader

How to generate a spreadsheet from a template, populate the spreadsheet, import and load the data, and fix any errors.

Postload Processing This table describes describes chapters chapters 23 through 25. Chapter

Title

Contents

23

Postload Processing for HCM Data Loader

Processes that you must run after loading specific business objects using either HCM Data Loader or HCM Spreadsheet Data Loader.

24

Purging Person Data from Test Environments

Processes to run in test environments to purge person and dependent data.

25

HCM Extracts and Diagnostics for HCM Data Loader and HCM Spreadsheet Data Loader

How to configure and run HCM extracts for HCM Data Loader. How to run the HCM Data Loader Error Analysis Report diagnostic test and the HCM Spreadsheet Data Loader diagnostic report.

3

Oracle Human Capital Management Cloud

Chapter 1

Integrating with HCM

Introduction to Integrating with Oracle HCM Cloud

Best Practices This table describes describes chapter chapter 26. Chapter

Title

Contents

26

Best Practices for HCM Data Loader and HCM Spreadsheet Data Loader

Recommended approaches to data creation and maintenance.

Chapter

Title

Contents

27

Payroll Data Loading

An overview of the ways in which you can load payroll data both during setup and later.

28

Payroll Batch Loader

Using the payroll batch loader tasks to load payroll business objects, such as element entries and payroll definitions, to Oracle HCM Cloud. Creating a report to view batch line errors. Using the payroll batch loader to migrate elements and formulas between environments.

29

Payroll Batch Loader Using Workbooks

Details of batch statuses and examples showing how to use tasks in the workbooks to load fast formula globals and element entries.

30

Payroll Batch Loader File Loading

Using the Load Batch from a File process,

automating file uploads, and details of file formats and data transformation. Details of the Batch Loader Formula Type formula and sample formulas for using it for f or transformation or for multiple tasks.

31

Payroll Batch Loader Workbooks

Details of the workbooks for balance adjustments, costing setups, elements, payment methods, payroll relationships, third-party organizations, and user-defined tables.

32

Time, Absence, Absence, and Pensio Pension n Data for Pay Payroll roll

Loading third-party time entries, pension deductions, and absence information in XML format to Oracle Global Payroll.

Loading Payroll Data This table describes describes chapters chapters 27 through 32.

4

Oracle Human Capital Management Cloud

Chapter 1

Integrating with HCM

Introduction to Integrating with Oracle HCM Cloud

Extracting Data This table describes describes chapters chapters 33 through 37. Chapter

Title

Contents

33

Managing HCM Extracts

Using HCM Extracts to extract data from Oracle HCM Cloud.

34

Filtering and Delivering HCM Extracts

Filtering HCM Extracts data and selecting a delivery format.

35

Flow Patterns

Using flow patterns to complete extract reports and processes.

36

Benefits Data Extract

Setting up benefits plan carriers and extracting benefits enrollment information into an XML file for each carrier.

37

Talent Review and Succession Succession Management Data Extract

The user entity, entity, database items group, and extract definition type for the Talent Review and Succession Management data that you can extract using HCM Extracts.

Transferring Encrypted Data This table describes describes chapter chapter 38. Chapter

Title

Contents

38

Transferring Encrypted Encrypted Data

How to set up data encryption. How to

upload and extract encrypted data.

Oracle Taleo Recruiting Cloud Service Integration This table describes describes chapter chapter 39. Chapter

Title

Contents

39

Oracle Taleo Recruiting Cloud Service Integration

How integration between Oracle Taleo Recruiting Cloud Service and Oracle HCM Cloud is managed.

5

Oracle Human Capital Management Cloud

Chapter 1

Integrating with HCM

Introduction to Integrating with Oracle HCM Cloud

Web Services This table describes describes chapter chapter 40. Chapter

Title

Contents

40

Web Services

Using web services to integrate web-based applications with Oracle HCM Cloud.

Inbound Integrations: Explained This topic introduces introduces ways of developing inb inbound ound integrations to Oracle HCM Cloud. These include: include: • HCM Data Loader • HCM Spreadsheet Data Loader • Payroll Batch Loader

HCM Data Loader Use HCM Data Loader to load data in bulk from any source to Oracle HCM Cloud. HCM Data Loader loads: • Complex, hierarchical data • Large volumes of data, such as complete system extracts • Object history You can use HCM Data Load Loader er for both data migration and ongoing ongoing data mai maintenance. ntenance. Major Major benefits of HCM Data Loader Loader include support for: • Most HCM business objects • Incremental or partial data loading • Four types of keys to identify records uniquely • Configured descriptive flexfields and extensible flexfields, translation data, tree hierarchies, person images, and document-record document-rec ord attachments HCM Data Loader provides: • A comprehensive comprehensive user interfa interface ce for initiatin initiating g data upload upload,, monitoring progress progress,, and reviewing reviewing errors • A template file for each supported supported business-object business-object hierarchy, whic which h you can use as the basis basis for your own data files interface for reviewing the the structure and attributes of every every supported bu business-objec siness-objectt hierarchy • A user interface • A web service service that you can use to automate automate data upload upload

6

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 1

Introduction to Integrating with Oracle HCM Cloud

Note: The precursor of HCM Data Loader Loader is HCM File-B File-Based ased Loade Loader. r. For information, see Overview: Transitioning from HCM File-Base File-Based d Loader to HCM Data Loade Loaderr (2206596.1) on My Oracl Oracle e Support at https:// https:// support.oracle.com.

HCM Spreadsheet Data Loader Use HCM Spreadsheet Data Loader to import data to the HCM Data Loader stage tables from spreadsheets. HCM Spreadsheett Data Loader supports most of the business objects that HCM Data Loader supports. It offers both ease of use Spreadshee and flexibility. For example, you can configure spreadsheet templates templates to suit business needs by omitting attributes, changing attribute order, changing attribute labels, and adding help text.

Payroll Batch Loader Use Payroll Batch Loader to load payroll business objects into Oracle HCM Cloud. You deliver a .zip file to the Oracle WebCenter WebCenter Content serve server. r. Payroll Batch Loader: 1. Imports the file contents to the Payroll Batch Loader stage tables 2. Loads payroll business objects from the Payroll Batch Loader stage tables to the application tables

You can automate automate both step stepss in the Payroll Payroll Batch Load Loader er process usi using ng the Flow Ac Actions tions Service web web service. Related Topics

• HCM Data Loader: Overview • Using HCM Spreadsheet Data Loader: Points to Consider • Payroll Batch Loader Tasks: Explained

Outbound Integrations: Explained This topic introduces introduces ways of developing outb outbound ound integrations from Oracle HCM Cloud. These include: include: • HCM Extracts • Oracle Business Intelligence Publisher (Oracle BI Publisher)

HCM Extracts The main way way to retrieve data in bulk from Orac Oracle le HCM Cloud is HCM Extracts, which is a tool for generating data data files and reports. HCM Extracts has a dedicated interface for specifying the records and attributes to be extracted. You: • Identify records for extraction using complex selection criteria. • Define data elements in an HCM extract using fast formula database items and rules.

7

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 1

Introduction to Integrating with Oracle HCM Cloud

You manage HCM Extracts either either in the Data Exchange work a area rea or using the Checklists interface interface in the Payroll work area. Alternatively, you can run extra extracts cts using the Flow Actions Service Service web sservice ervice from outside outside Oracle HCM Cloud. This feat feature ure enables you to automate the outbound extract as part of an overall integration flow.

HCM Extracts Output Formats Using the built-in integration with Oracle BI Publisher, you can generate extracts in various formats, including CSV, XML, Microsoft Excel, HTML, RTF, and PDF. You can download download the raw hi hierarchical erarchical XML XML from a comple completed ted extract using the Extra Extract ct Actions Service Service web service. service. Alternatively, you can downloa download d the formatted BI report (for example, example, the CSV file) using the BI ScheduleService. ScheduleService. In both cases, the output is streamed in a byte array. Therefore, any orchestration mechanism mechanism must handle this output, possibly by means of wrapper code. You can also generate an H HCM CM Extract withou withoutt specifying an output format at the design stage. stage. Subsequently, Subsequently, you can can generate a BI report based on the extract using either Oracle BI Publisher or the BI ReportService. This technique technique uses a dedicated BI data model that interfaces with the generated HCM Extracts XML.

Oracle BI Publisher Oracle BI Publisher supports both scheduled and unplanned reporting, based on either predefined Oracle Transactional Business Intelligence Intelligence analysis structures or your own data models. You can generate reports in various formats. To use Oracle BI Publisher for outbound integrations, you generate reports in a format suitable for automatic downstream processing, such as XML or CSV.

8

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 2

Introduction to HCM Data Loader

2 Introduction to HCM Data Loader HCM Data Loader: Overview HCM Data Loader is a powerful tool for bulk-loading and maintaining data. The data can be from any source. You can use HCM Data Loader for data migration, ongoing maintenance of HCM data, and coexistence scenarios, scenarios, where core HR data is uploaded regularly. This topic introduces the main features and advantages of HCM Data Loader.

Business-Object Support You can load business ob objects jects for most Ora Oracle cle Fusion Human Human Capital Management Management (HCM) (HCM) products. These These products include Oracle Fusion Absence Management, Compensation, Global Human Resources, Global Payroll, Performance Management, Profile Management, Talent Review and Succession Management, and Workforce Management. You can also update business objects using HCM Data Loader, regardless of how they were created.

Ease of Use HCM Data Loader has a comprehensive user interface for loading data, monitoring progress, and reviewing any errors. It provides real-time information for all stages of its processing. HCM Data Loader's user interface also includes detailed information about the component hierarchies and attributes of supported business objects. You can load data from eithe eitherr delimited data (.dat) files or spreadsheets. spreadsheets. You c can an load most supported business business objects objects using either method. You can generate business-object business-object templates to use as the basis of your own .dat files. For a selected business-object business-ob ject component, the template includes every attribute, including those for configured flexfields. When using spreadsheets, spreadshee ts, you define spreadsheet templates to suit business needs and generate spreadshee spreadsheets ts from those templates.

Performance HCM Data Loader supports multithreaded processing, which enables you to upload complete data extracts without severe performance impacts. References References among objects that are processed on separate threads are managed automatica automatically. lly. You can set HCM Data Loader configuration parameters to optimize processing for your environment. You can also perform partial or incremental lloads oads to update update existing ob objects, jects, thereb therebyy minimizing the related processing. processing.

Supported Key Types HCM Data Loader supports all of the following key types for most business objects: objects: • Oracle Fusion GUID • Oracle Fusion surrogate ID • Source key

9

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 2

Introduction to HCM Data Loader

• User key As user keys and source ke keys ys are supporte supported, d, knowledge of Oracle Fusion internal IDs isn't isn't required.

Business-Object Features HCM Data Loader supports most business-object business-object features and requirements. For example, you can upload: • Current and historical records for date-effective objects. You determine the amount of history to load. • End-dated, terminated, terminated, or inactive records. • Translated attributes attributes in multiple multiple languages. languages. You spec specify ify the character character set of the d data ata file on the the File Character Set configuration parameter for HCM Data Loader. • Descriptive flexfields and extensible flexfields. • Hierarchical tree data, such as organization and department trees. • Attachments and pictures. pictures. • Data from multiple sources. You can include source-system references in uploaded data.

Automation You can initiate initiate HCM Data Loader using a web-service call, which enables you to automate d data ata upload.

HCM Data Loader and Implementation Scenarios: Overview You can implement implement Oracle HCM Cloud in e either ither full or coex coexistence istence mode. mode. In a coexistence coexistence implementation, implementation, you use Oracle Fusion Talent Management or Oracle Fusion Compensation, but continue to use your existing HR applications. applications. For both full and coexistence implementations, you implement implement Oracle HCM Cloud by performing the tasks that appear in your implementation project or for selected functional areas. This topic describes how HCM Data Loader supports these implementation implementa tion types.

Full Implementations If you're performing a full implementation of Oracle HCM Cloud, then you can use HCM Data Loader to bulk-load any existing HCM data at appropriate stages in the implementation. Typically, you load each type of data once only for this type of implementation. implementa tion. Following successful upload, you manage your data in Oracle HCM Cloud.

Coexistence Implementations In a coexistence implem implementation, entation, you use Oracle Fusion Talent Management or Oracle Fusion Compensation, but maintain your existing HR applications. For this type of implementation, implementation, you: • Move talent data permanently to Oracle HCM Cloud, which becomes the application of record for talent data.

10

Oracle Human Capital Management Cloud

Chapter 2

Integrating with HCM

Introduction to HCM Data Loader

• Upload other types of data, such as person records, periodically to Oracle HCM Cloud. The source system remains the application of record for this data. To implement an HCM coexistence coexistence sce scenario, nario, for any source system, you ca can n use HCM Dat Data a Loader for dat data a upload. Follow the general instructions provided for HCM Data Loader. Oracle doesn't supply tools to extract data from your source systems. Work with your implementation partner or develop your own process for extracting the source data. HCM Data Loader provides a Compensation Changes extract. You can extract assignment, bonus, and salary changes for a specified compensation compensation run if you're using Oracle Fusion Compensation in a coexistence scenario.

HCM Data Loader Process: Explained This topic outlines outlines the process process of loading d data ata in bulk from .dat files using HCM Data Loader. The data data can be from any source. This figure provides provides a high-level high-level summary of the process.

HCM Data Loader

To WebCenter Content Import

Stage Tables

Import Errors Load Errors Load

Application Tables Tables

The steps of this process are: are: 1. You place a .zip file cont containing aining your .dat files on the Oracle Oracle WebCenter WebCenter Content server. 2. You request or to HCM Data Loader to importer and loa load d the .zip file file.. For this step, step, you can use either the HCM Datasubmit Loaderainterface the HcmCommonDataLoad HcmCommonDataLoader web service.

11

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 2

Introduction to HCM Data Loader

3. HCM Data Loader decompresses the .zip file and imports individual data lines to its stage tables. In the stage tables,

related data lines are grouped to form business objects. Any errors that occur occur during the import import phase are are reported on th the e HCM Data L Loader oader interface. interface. 4. HCM Data Loader calls the relevant logical object interface method (delivered in product services) to load valid objects to the application tables. Any errors that occur occur during the load load phase are are reported in the HCM Data Loader interface interface.. errors from the import a and nd load phases. phases. You can perform this step step either on the HCM Data Loader Loader 5. You review any errors interface or using the HCM Data Loader Data Set Summary extract.

6. You correct errors from the import and load phase phasess in your source data. 7. You load a new new .zip file con containing taining the corrected corrected data to the WebCent WebCenter er Content server.

You repeat this this process from step step 2 until al alll of the data is successfully successfully loaded. also correct load e errors rrors interactively on the HCM Data Loader interfac interface e and resubmit resubmit any Tip: You can also corrected data from there. Related Topics

• Uploading Data Using HCM Spreadsheet Data Loader: How It's Processed

Supported Key Types: Explained When planning to integrate data from one system to another, you must select key types to identify records uniquely. This topic introduces the key types that HCM Data Loader supports.

What Keys Identify In HCM Data Loader, you use unique keys to identify: that you're creating or updating. • The record that • The parent of the the record that you're creating or updating. The parent record record may eithe eitherr be in the ssame ame data file file or exist already already in Oracle HCM Cloud. referenced by the the record that you're creating or updating. updating. • Any objects referenced

Supported Key Types HCM Data Loader supports the following key types, which you can use for all types of object references. When more than one key value exists for an object, key references are resolved in this order: 1. 2. 3. 4.

Oracle Fusion Globally Unique Identifier (GUID) Source key Oracle Fusion surrogate ID User key

If you supply multiple key values, then no cross-validati cross-validation on occurs. For example, if you supply both a GUID and a source key, then the GUID is used and the source key is ignored. If the source key identifies a different record from the GUID, then no error is raised.

12

Oracle Human Capital Management Cloud

Chapter 2

Integrating with HCM

Introduction to HCM Data Loader

Tip: Whenever possible, use source keys for both creating and updating business objects.

Key-Type Features The following table table summarizes the main fe features atures of the available available key types. types. The Create and Update columns indicate whether you can use the key type when creating and updating objects.

Key Type

Create

Update

Held on Object

Type

Generated Automatically

GUID

No

Yes

No

Hexadecimal

Yes

Surrogate ID

No

Yes (see note)

Yes

Numeric

Yes

Source Key

Yes

Yes

No

Alphanumeric

Conditionally (see note)

User Key

Yes

Yes (see note)

Yes

Alphanumeric

No

Note: You can use surrogate surrogate IDs when updating obje objects, cts, but the IDs may not be readily availa available ble to Oracle

HCM Cloud users. Default source keys are generated only if you don't supply a source key when creating an object. You can't use user keys alone when updating some objects because their values are subject to change. Keys that aren't held on the object exist in the Integration Key Map table.

Foreign-Object References Oracle Fusion GUIDs and surrogate IDs are generated only when the associated record is successfully successfully created in Oracle HCM Cloud. Source keys aren't recognized in Oracle HCM Cloud until the associated record exists in Oracle HCM Cloud. Therefore, before you attempt to lload oad data that that references fore foreign ign objects, you must ensure that those foreign objects exist exist in Oracle HCM Cloud. For a new implementation, you're recommended to load each business object separately and ensure that it loads successfully before importing the next. If you supply all business objects in the same .zip file, then HCM Data Loader loads them in order of dependency. dependency. In this case, a reference to a foreign object fails only if the referenced object failed to load.

Source Keys: Explained A source key is is the ID that identifies identifies a business object object in its source source system. Source Source keys are supported only for integrationintegrationenabled business objects. You can use source keys when creating or updating business objects. You're recommended to use source keys for all implementations implementations but particularly for ongoing integrations, where data is maintained in the source system.

Source-Key Structure A source key has has the two com components ponents shown in this table. table.

13

Oracle Human Capital Management Cloud

Chapter 2

Integrating with HCM

Introduction to HCM Data Loader

Component

Description

Source-system owner Source-system

Identifies where the data originated.

Source-system ID Source-system

ID used in the source system. The ID must be unique for the business-object component and source-system source-syst em owner.

Having a source-system owner component to the key enables you to upload data from multiple source systems for the same business objects. For example, example, you may have person data in both US and UK databases to combine in one Oracle HCM Cloud system. The source-system ID doesn't have to be unique across both source systems. It must be unique only for the business-object business-ob ject component and source-system owner. If you don't have an obvious source-system ID for a record, then you can generate or derive one. For example, you could derive a source-system ID for a person address by concatenating the person number with the address type. Source keys aren't held against the created record. They exist in the Integration I ntegration Key Map table.

Source Keys for Date-Effective Business Objects If you're supplying date-effective history for an object, then you must supply the source system IDs for every date-effective record in the file. The values must be the same for each line of the date-effective history.

Default Source Keys If you provide no source key when creating an object, then the source key is created automatically. The default sourcesystem owner is FUSION and the default source-system ID is the surrogate ID. You can update the source key later using the Source Key business object. In the Source Key business object, you supply the new source key and a reference to the object that you're updating.

Source-System Owner Values The source-system source-system owner value is validated against the H HRC_SOURCE_SYSTEM RC_SOURCE_SYSTEM_OWNER _OWNER lookup type. type. You must add add your source-system names to this lookup type before loading data using source-system references. Use the Manage Common Lookups task in the Setup and Maintenance work area to update HRC_SOURCE_SYSTEM_OWNER.

User Keys: Explained Most Oracle HCM Cloud business objects, regardless of whether they're enabled for integration, have one or more attributes that make up a user key. The user key, which is also known as a natural key, is always visible on the user interface. For example: • The user key for an an organization is the organization name. • The user key for an an area of responsibility responsibility is th the e responsibil responsibility ity name plus the person number. number.

14

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 2

Introduction to HCM Data Loader

When to Use User Keys User keys are part of the business object definition. They're always required when you create a logical object, regardless of how you create it. You can also use user keys when updating updating logical obje objects. cts. However, the value of a user user key can change, change, and some some user-key attributes are translatable. translatable. For this reason, you can't update some business objects if you supply only user keys to reference them. Therefore, whenever possible, you're recommended to use source keys when updating objects. User keys are recommended when: referencing or maintaining an object th that at wasn't created created with a source key. • You're referencing • The source-key source-key value is unknown. unknown.

User Keys for Child Objects When a business object is bound by another, the user key must include the user key for its parent. For example: • Jobs are always part of a set. Therefore, job code alone doesn't uniquely identify a job. Instead, the set code must be part of the user key for a job. • Job grades apply to a specific job. Therefore, the user key for a job grade must include both the user key for the grade and the user key for the parent job. Therefore, the user key for the job grade is made up of the grade code, job code, and and set code code..

Oracle Fusion GUIDs and Surrogate IDs: Explained Oracle Fusion Globally Unique Identifiers (GUIDs) and surrogate IDs are two of the four types of keys that HCM Data Loader supports. This topic describes when you can use GUIDs and surrogate IDs to identify business objects uniquely. uniquely.

Oracle Fusion GUIDs When you create an integration-enabled business business object in Oracle HCM Cloud, a GUID is generated for the object automaticall automatically. As the generated when youcreating create the businessobject. object,The it's GUID, suitable only for identifying that already y. exist. YouGUID can'tissupply a GUID when a business a hexadecimal value,business isn't heldobjects on the created object but exists in the Integration Key Map table. GUIDs are useful when you share changes with down-stream applications, applications, such as third-party payroll providers. You extract the changes for the third-party payroll and provide the GUID as the unique key to the worker. When reporting any updates back to Oracle HCM Cloud, you can use GUIDs to identify the records r ecords to update.

Oracle Fusion Surrogate IDs The surrogate ID, a numeric value, value, is the iinternal nternal system identifier that that's 's generated when you create create a business business object. All All objects, including those that aren't integration-enabled, integration-enabled, have surrogate IDs. The surrogate ID is held on the object. The ID is also used in the Integration Key Map table to provide a mapping for GUID and source-key values. As the surrogate ID isn't generated until the object is created, you can't use this value when creating objects. Access to surrogate IDs may also be limited. On-premises On-premises customers are more likely to have access to surrogate IDs than Oracle HCM Cloud customers.

15

Oracle Human Capital Management Cloud

Chapter 2

Integrating with HCM

Introduction to HCM Data Loader

Business-Object Structure: Explained Each Oracle HCM Cloud business object is a hierarchy of business-object components. At the top of the hierarchy is the parent component, and beneath it may be child and grandchild components. Each business-object component has multiple attributes. This figure shows a generic b business-obje usiness-object ct structure.

Parent Component Attributes

Parent Component

Child Component

Child Component Attributes

Child Component

Child Component Attributes

For example, the Rating Model business object includes Rating Model, Rating Level, and Rating Category components. The Rating Model component is the parent of the other two components. Each component has attributes such as RatingName, RatingModelCode, RatingLevelCode, and so on. The most complex complex business business object supported supported by HCM Data Data Loader is the Worker object, object, where five levels levels exist in in the object hierarchy. These range from the Worker component at the top to Assignment Work Measure, Assignment Manager, Assignment Grade Grade Steps, and Assignment Assignment Extra Information at the bottom. By contrast, the the Person Type object has on only ly the Person Type component.

Terminology This table defines defines the terms terms used by HCM Data Load Loader er to refer to busi business ness objects. objects. Term

Meaning

Object or business object

Refers to the complete object, which is the parent component and all child components. For example, Grade and Worker are business objects.

16

Oracle Human Capital Management Cloud

Chapter 2

Integrating with HCM

Introduction to HCM Data Loader

Term

Meaning

Component or business-object component

Refers to components of a business object. For example, Person Name and Work Relationship are components of the Worker object.

Logical object

Refers to a group of related components that form one occurrence of a business object. For example, the grade IC1 is a logical object.

Loading Logical Objects When you deliver multiple components for the same business object together, HCM Data Loader groups them and loads the complete logical object. It doesn't process the components separately. separately. If any component of the logical object fails validation, then the whole logical object is rejected. As HCM Data Loader loads only complete logical objects, you can be sure of exactly which data has been loaded. For example, when loading jobs, you know which jobs loaded successfully and which jobs failed to load.

Integration-Enabled Integration-Enabled Objects HCM Data Loader can load any integration-enabled business object. An integration-enab integration-enabled led business object supports these four key types: • Oracle Fusion GUID • Oracle Fusion surrogate ID • Source key • User key An integration-enabled integration-enabled object object has an entry in the Integration Integration Key Map table, where its GUIDs and source keys e exist. xist. HCM Data Loader can also load a few f ew objects, such as Department Tree, that aren't integration enabled. Typically, Typically, Oracle HCM Cloud doesn't own such objects and they support neither source keys nor GUIDs. Tip: You can review business-ob business-object ject detail detailss on the View Business Objects Objects page. The Integration Keys Supported field on the Component Details tab for a selected component indicates whether whether the component is

integration enabled. Related Topics

• Finding Business-Object Information: Explained

FAQs for Introduction to HCM Data Loader Why can't I access HCM Data Loader? You may not have the correct p permissions. ermissions. You must have the Human Capita Capitall Managemen Managementt Integration Specialist Specialist job role or privileges to access HCM Data Loader.

17

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 2

Introduction to HCM Data Loader

18

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

3 Data File Instructions and Delivery HCM Data Loader Data and .zip Files: Explained HCM Data Loader loads data from .zip files. Each .zip file can contain one or more data (.dat) files. Each data file includes data for a single business object, such as Location, Grade, Worker, or Salary. The data file has the name of a business object that is supported by HCM Data Loader, such as Job.dat or Worker.dat. The name of the data file is specified by HCM Data Loader. In any .zip file, you supply data files only for the business objects that you're loading. This figure shows an exampl example e .zip file st structure. ructure. The .zip file contains no no folders for data (.dat) files.

You define the name of the .zip file, which which must be iin n alphanumeric alphanumeric characters characters (a-z, A-Z, and 0-9). The .zip file can can be encrypted as a whole, but HCM Data Loader doesn't support the encryption of individual data files.

BlobFiles and ClobFiles Folders in the .zip File The only two folders folders that can appear appear in the .zip file are: • BlobFiles, which is for binary large objects • ClobFiles, which is for character large objects In these folders you place files to be loaded either as attachments or into large objects. The file names of these attachments or images must be in alphanumeric characters (a-z, A-Z, and 0-9). 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 the Document Record object is used for loading attachment files and has a data type of BLOB. Therefore, you place files to be loaded as attachments to document records in the BlobFiles folder.

19

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

This figure shows an exampl example e .zip file st structure ructure when attachments attachments are are included.

The contents of the BlobFiles BlobFiles folder in this example a are re as shown iin n this figure.

Data Files Each HCM Data Loader data file is specific to a business object. You provide all components that you want to load for f or a business-object business-ob ject hierarchy in the same data file. For example, you provide Job, Job Valid Grade, Job Evaluation, Job Extra Information, and Job Legislative Extra Information components in Job.dat. This approach enables you to see all data for a business object and supports the validation of parent references on all child components. It also simplifies the construction of the .zip file, as separate directories aren't required and fewer data files have to be generated. generate data-fil data-file e templates for all supporte supported d objects on the View Business Business Objects Objects page. Eac Each h Tip: You can generate template defines the complete structure of the selected object. Related Topics

• Loading Images, Attachments, and Large Strings: Explained

File Line Instructions and File Discriminators: Explained Each line in a data file begins with an instruction, and most lines include a file discriminator. This topic introduces the available instructions and describes the file discriminators.

File Line Instructions This table identifies identifies the instructions tha thatt can appe appear ar in an HCM Data Loader data data file.

20

Oracle Human Capital Management Cloud

Chapter 3

Integrating with HCM

Data File Instructions and Delivery

Instruction

Line Type

Description

METADATA

Definition

Identifies the business-object component and the attributes of that component for which you're including values in the data file

MERGE

Data

Provides data to be merged in Oracle HCM Cloud

DELETE

Data

Identifies a business-object component to be purged from Oracle HCM Cloud

SET

Control

Overrides aspects of the default processing for a file

COMMENT

Comment

Adds a comment comment to the da data ta file

File Discriminators METADATA, MERGE, and DELETE lines must include a file discriminator value, which identifies the business-object business-object component which the instruction applies. For example, the available file discriminators for the Job business object are shown in thistotable.

Business-Object Co Component

File Di Discriminator

Job

Job

Job Valid Grade

JobValidGrade

Job Evaluation

JobEvaluation

Job Extra Information

JobExtraInfo

Job Legislative Extra Information

JobLegislative

The file discriminator discriminator appears appears immediately immediately after the iinstruction nstruction in a file line. HCM Data Loader templates for a business object object include the file discriminator for each of the object's components. This example shows instructions, the file discriminator, attribute names, and attribute values for the Job business object. METADATA|Job|Effec METADATA| Job|EffectiveStartD tiveStartDate|Effect ate|EffectiveEndDat iveEndDate|SetCode| e|SetCode|JobCode|N JobCode|Name ame MERGE|Job|1950/01/01|4712/12 MERGE|Job|1950/01/ 01|4712/12/31|COMMON /31|COMMON|CFO|Chie |CFO|Chief f Financial Financial Officer MERGE|Job|1950/01/ MERGE|Job |1950/01/01|2013/01 01|2013/01/01|COMMON /01|COMMON|PM|Manag |PM|Manager er Projects Projects MERGE|Job|2013/01/ MERGE|Job |2013/01/02|4712/12 02|4712/12/31|COMMON /31|COMMON|PM|Manag |PM|Manager er Projects Projects MERGE|Job|1950/01/ MERGE|Job |1950/01/01|4712/12 01|4712/12/31|COMMON /31|COMMON|VP_OF_HR |VP_OF_HR|VP |VP Human Resources MERGE|Job|1950/01/ MERGE|Job |1950/01/01|4712/12 01|4712/12/31|COMMON /31|COMMON|PROG_MGR |PROG_MGR|Program |Program Manager Manager

In this example: • The instruction, METADATA or MER MERGE, GE, appea appears rs at the start of the line. • The discriminator discriminator on all lines lines is Job.

21

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

• Attribute names names appear iin n the METADATA line after the Job discriminator discriminator and separated separated by the vertical vertical bar character character (|). • Attribute values values appear in MERGE lines after the Job discriminator and and separated by the vertical bar character character (|).

Instruction: The METADATA Instruction: Explained Explained The METADATA instruction in an an HCM Data Loa Loader der data file identifies a business-ob business-object ject componen componentt and its attributes. attributes. The attributes are those for which you're including values in the data file.

Instruction Format The METADATA line has this format: METADATA|

For example: METADATA|JobFamily|Effective METADATA|JobFamily |EffectiveStartDate| StartDate|Effective EffectiveEndDate|Jo EndDate|JobFamilyNa bFamilyName me DELETE|JobFamily|2012/10/01|4712/12/31|Sales01

Restrictions These restrictions restrictions apply to th the e DELETE instruction: instruction: delete a busine business ss object or a component of a business object. object. However, you can't delete delete individual date• You can delete effective records. provide MERGE and DELETE instructi instructions ons for the same record in a single single data file. file. The order in which which HCM • You can't provide Data Loader processes instructions is unpredictabl unpredictable. e. recover deleted re records. cords. Therefore, try to correct data rather than delete delete and recreate recreate it. • You can't recover • Not all business-object components can be deleted. For information about deletion support, see the business-object details available from the View Business Objects page in the Data Exchange work area.

The SET Instruc Instruction tion The SET instruction instruction is optional in a .dat file file and has no discriminator. discriminator. You use SET iinstructions nstructions to alter alter default processing processing for the file in which they appear. You can include any number of SET instructions in a .dat file, but they must appear before the first METADATA line. This topic describes when to use the SET instruction. This table lists lists the SET iinstructions nstructions and their default values.

Instruction

Default Value

SET PURGE_ FUTURE_CHANGES Y|N

Y

SET DISABLE_ POST_ PROCESS_

Not applicable

TASKS

24

Oracle Human Capital Management Cloud

Chapter 3

Integrating with HCM

Data File Instructions and Delivery

Instruction

Default Value

SET INVOKE_ POST_PROCESS Y|N

Y

SET FILE_ DELIMITER

Vertical bar (|)

SET FILE_ESCAPE

Backslash (\)

SET FILE_NEWLINE

n

SET ENABLE_ AUDIT_DATA Y|N

N

SET PURGE_ AUDIT_DATA Y|N

N

SET CALCULATE_FTE Y|N

N

SET CREATE_ DEFAULT_ WORKING_ HOUR_ PATTERN Y|N

N

Tip: The default values shown h here ere are predefined predefined for the e enterprise. nterprise. You c can an override these these values for the enterprise using the Configure HCM Data Loader task in the Setup and Maintenance work area.

SET Instruction Descriptions This section provides an alphabetic alphabetic list list of all SET in instructions structions with their their description descriptions. s. SET CALCULATE_FTE

To request automatic automatic calc calculation ulation of full-time full-time equivalen equivalentt (FTE) values for all worker assignments assignments in a Worker.dat file, include include the SET CALCULATE_FTE instruction. For example: SET CALCULATE_FTE Y

SET CREATE_DEFAULT_WORKING_HOUR_P CREATE_DEFAULT_WORKING_HOUR_PATTERN ATTERN

To request automatic automatic creati creation on of a default working-hour pattern pattern for all worker ass assignments ignments in a Worker.dat file, include the SET CREATE_DEFAULT_WORKING_HOUR_PATTERN instruction. For example: SET CREATE_DEFAULT_WORKING_HOUR_PATTERN Y

SET DISABLE_POST_PROCESS_TASKS DISABLE_POST_PROCESS_TASKS

By default, these processes run automatically after you load workers: • Refresh Manager Hierarchy • Update Person Search Keywords To prevent Refresh Manager Hierarchy  from from running automatically, automatically, you can include this SET instruction in the Worker.dat file:

25

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

SET DISABLE_POST_PROCESS_TASKS RefreshManagerHierarchy

To prevent Update Person Search Keywords from running automatically, automatically, you can include this SET instruction in the Worker.dat file: SET DISABLE_POST_PROCESS_TASKS UpdatePersonSearchKeywords

FlattenPositionHierarchy  process By default, the FlattenPositionHierarchy process runs automatically after you load HCM position hierarchies. To prevent FlattenPositionHierarchy  from running automatically, include this SET instruction in the PositionHierarchy.dat file: SET DISABLE_POST_PROCESS_TASKS FlattenPositionHierarchy

Tip: To prevent postload postload processes from running autom automatically, atically, you can can use the SET INVOKE_POST_PROCESS

instruction instead. SET ENABLE_AUDIT_DATA

Audit of objects objects loaded u using sing HCM Data Loader is ena enabled bled or disabled disabled for the en enterprise terprise using the Enable Audit Data configuration parameter. parameter. You can override the enterprise setting for individual .dat files by including this SET instruction. For example, if audit is enabled for the enterprise, then you can disable it for an individual .dat file. SET FILE_DELIMITER

Use this instruction to change the default file delimiter, which is the vertical bar (|). For example, to change it to a comma, include this instruction: SET FILE_DELIMITER ,

The new value can be up to 10 characters. characters. SET FILE_ESCAPE

Use this instruction to change the default file escape character, which is the backslash (\). For example, to change it to the equal sign (=), include this instruction: SET FILE_ESCAPE =

The new value can be up to 10 characters. characters. SET FILE_NEWLINE

Use this instruction to change the default file newline character, which is the character n. For example, to change it to the string newline, include this instruction: SET FILE_NEW_LINE newline

The new value can be up to 10 characters. characters. SET INVOKE_POST_PROCESS INVOKE_POST_PROCESS

By default, these processes run automatically after you load workers: • Refresh Manager Hierarchy • Update Person Search Keywords By default, the FlattenPositionHierarchy  process runs automatically after you load HCM position hierarchies.

26

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

To prevent such such processes from running automat automatically, ically, you can include this this SET instruction in the relevant relevant .dat file: SET INVOKE_POST_PROCESS N

SET PURGE_AUDIT_DATA

Use this instruction to purge the audit data for the objects in a .dat file. This feature is intended primarily to remove the audit records for personally identifiable information in worker records. You can't include include both of th the e following instruc instructions tions in a single single .dat file: • SET

ENABLE_AUDIT_DATA Y

• SET

PURGE_AUDIT_DATA Y

If auditing of loaded objects is enabled for the enterprise, then you must disable it in any .dat ffile ile where you're purging audit data. That is, you include the following instructions: • SET

ENABLE_AUDIT_DATA N

• SET

PURGE_AUDIT_DATA Y

SET PURGE_FUTURE_CHANGES PURGE_FUTURE_CHANGES

When you create business objects containing date-effective components, components, you include this instruction at the start of the file: SET PURGE_FUTURE_CHANGES PURGE_FUTURE_CHANGES Y

This instruction se sets ts the date-effective maintenance mode to Replace. to Replace. In this mode, which is the default mode, the contents of the .dat file replace any existing data. When you update business objects containing date-effective components, you include this instruction at the start of the file: SET PURGE_FUTURE_CHANGES N

This instruction sets the da date-effective te-effective maintenance maintenance mode to Retain. Retain. In this mode, mode, any existing existing future-date future-dated d changes are are retained. Related Topics

• Managing Reserved Characters: Explained • Loading Date-Effective Objects: Overview • Enable Audit for Oracle HCM Cloud Business Objects • HCM Data Loader Configuration Parameters

Generating and Using Template Files: Procedure HCM Data Loader provides a template file for each supported business-object business-object hierarchy. The template contains: • A COMMENT line, line, which identifies identifies the business business objec object, t, its version, and the file-creation file-creation date. date. • A METADATA line line for each c component omponent of the business-object business-object hierarchy tthat hat you can load load for the business business object. The METADATA line includes includes every attribute of the compone component, nt, including environment-specific environment-specific configured configured flexfield attributes.

27

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

You can generate generate template files and u use se them as the basis of your own data files. files. The topic describes how how to generate a and nd use template files.

Generating a Single Template File Follow these steps: 1. Open the Data Exchange work area and select the View Business Objects task on the Tasks panel tab.

By default, the View Business Objects page lists all business objects that HCM Data Loader supports. You can sort the list by business object or load order, for example. You can also retrieve a specific object by entering its name in the Business Object query-by-example field and pressing Enter. 2. If a template already exists for the object, then you can click the Download File icon to download it. The Last Refreshed column shows when the template was generated. Alternatively, you can update the template before you download it, as follows: a. Select the object row in the business objects table. b. Click Refresh Object. c. In the Schedule Request dialog box, click Submit. Click OK  to to close the confirmation message.

When you click Submit, you start the process that generates the latest template file.

Tip: To monitor progress, click View Process Process Results to open the View Process Results page. 3. On the View Business Objects page, click the Refresh icon.

Check the value in the Last Generated column to confirm that the template has been updated. 4. Click the Download File icon to download the template.

Generating Template Files for All Business Objects Follow these steps to generate template files for all business objects in a product area or all business objects: 1. 2. 3. 4.

Click the Refresh All Objects button on the View Business Objects page. In the Schedule Request dialog box, you can either select a product area or leave Product Area set to All. Click Submit. When the generation process completes, you can download templates individually. individually. Click the Download File icon for an object on the View Business Objects page. Alternative Alternatively, ly, follow these steps to download a single .zip file of the generated templates: a. Click View Process Results. b. On the View Process Results page, click the Download File icon for your process.

Using Template Files Template files files identify the names of al alll available attributes of a business object, object, including including those of environment-specific environment-specific attributes, such as flexfield segments. segments. Don't simply copy the METADATA lines from the template file and use them in your own data files. Instead, include in your data files: • METADATA lines for the components that you want to load • Attribute names names for the value valuess you want to su supply pply

28

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

You can improve the speed and efficien efficiency cy of the import a and nd load processes processes by de declaring claring only the attributes for which which you're supplying data. Remove METADATA lines and attribute names that you don't intend to use. HCM Data Loader validates every attribute name on every METADATA line. It also identifies any potential depende dependencies ncies on other business objects in the same .zip file by reviewing the attributes supplied in METADATA. For example, the Job.dat file may contain a METADATA line for the Job Valid Grade component with the Grade ID attribute. In this case, HCM Data Loader assumes that the Job.dat file has a potential dependency on grades.

FAQs for Data File Instructions and Delivery How should I deliver data when creating objects? Deliver one object per .zip file. For example, create one .zip file for jobs, one for workers, and so on. Correct any errors before loading the next object to avoid data-reference errors.

How should I deliver data for incremental updates? Supply only changed and required attribute values. Deliver all business-object files in the same .zip file. HCM Data Loader processes them in the correct order and loads referenced data before the data that references it.

Can I include comments in a .dat file? Yes. Use the COMMENT instructio instruction n to add a comment comment to a .dat .dat file. For example: COMMENT Data for Business Object: Job Version: V2 Created on: 25-03-2017

You can include include any number number of COMMENT instructions instructions and the theyy can appear appear anywhere in the file. The Theyy have no effect on processing.

29

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 3

Data File Instructions and Delivery

30

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

4 Preparing to Use HCM Data Loader Finding Business-Object Information: Explained To load a business business object object or component ssuccessfully uccessfully using using HCM Data Loader, you must understand its its structure, supported supported key systems, data formats, and required attributes. You must also understand any business rules that apply to the object. This topic identifies identifies where you can find this this information.

Business-Object Details When you click the name of a business object on the View Business Objects page, you access information about the object. This information includes: • The component component hierarchy of the object. • Component details for the currently selected component. These include: ◦

◦

◦

◦

Its parent component, file discriminator, .dat file, and translation object Whether it supports integration keys Its supported actions, for example, whether you can delete the component Whether it's date effective and, if so, whether you can change the component's first start date and last end date

• Attribute details details for each attribute attribute of the currently selected selected component. component. These include: include: ◦

◦

◦

◦

◦

◦

Its name, type, and length Whether it's required always or for new objects only Whether it's a key value or can be used as a key value and, if so, the key type For attributes that are keys of type surrogate ID, parent surrogate ID, or foreign-object reference, reference, whether integration keys are also supported The names of any user-key a attributes ttributes that you can use in place of surrogate surrogate IDs Names of lookup types, for attributes that are lookup-validate lookup-validated d

If you can load flexfields for the component, then the Flexfield Attributes tab appears. For descriptive flexfields and extensible flexfields, you can see the attributes for a selected flexfield and context. For extensible flexfields, category also appears. When a flexfield context supports multirow entries, one or more flexfield attributes are identified as user keys to reference a single record uniquely. These attributes are identified in the User Key  column column on the Flexfield Attributes tab. This column doesn't appear if the flexfield doesn't support multirow entries. Tip: Click the Export to Excel icon to export the attribute details or flexfield details to a spreadsheet.

You can refresh business ob objects jects using th the e Refresh Object icon and the Refresh All Objects button. When you refresh an object: • Attribute and flexfield information information for the sel selected ected business business objects is updated. updated. • Up-to-date templates templates of METADATA lines are generated for the selected business objects.

31

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

You're recommended recommended to refresh all objects after an upda update. te. The refresh ensures that any changes from the update appear on the View Business Objects page and in object templates. If no details exist for a selected object when you view it, then you're prompted to refresh the object.

Business Rules Business rules for many objects are included in the Integrating with Oracle HCM Cloud guide. For objects that aren't described in the Integrating with Oracle HCM Cloud guide, see HCM Data Loader: Business Object Documentation Documentation (2020600.1) on My Oracle Support at https://support.oracle.com. https://support.oracle.com. This document also provides attribute descriptions and example .dat files for some business objects. Example .dat files for many business objects are also available on Cloud Customer Connect. Select Navigator > Others > Cloud Customer Connect. After signing in, select the HCM Cloud Integrations forum on the Human Capital Management page. Other documents on My Oracle Support provide information about business objects for specific localizations. localizations. Many are linked from the document All White Papers for Oracle Fusion HCM (1504483.1). For example: • Oracle Fusion HCM: HCM Address Validation (2140848.1) • Oracle Fusion HCM: Person Name Validation (2146270.1) National Identifie Identifiers rs in Oracle Fusion Fusion Human Ca Capital pital Manage Management ment (2159758.1) • Validating National Related Topics

• HCM Data Loader: Business Object Documentation (2020600.1)

HCM Data Loader Configuration Parameters The HCM Data Loader configurat configuration ion parameters control the HCM D Data ata Loader a and nd HCM Spreadsheet Spreadsheet Data Loader import and load processes. The default settings of the parameters suit most requirements. However, you can override these settings to suit the configuration of your environment and the amount of data being loaded. Users can also override most enterprise settings for individual individual load processes. In the Setup and Maintenance work area, use the following to review or override the predefined settings for the enterprise: • Functional Area: HCM Data Loader Loaderr • Task: Configure HCM Data Loade On the Configure HCM Data Loader page, select the HCM Data Loader tab. You can filter the parameters by these category values: • Availability • Diagnostics • File Definition • Performance • Scheduling Default Parameters that are specific to a business object appear in a separate section. This topic describes each of the configuration parameters within its category. Object-spe Object-specific cific parameters are described following the category sections.

32

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

Note: HCM Spreadsheet Data Loader has its own versions of some configuration parameters, parameters, which you manage on the HCM Spreadsheet Data Loader tab. For these parameters, you can set different default values for HCM Data Loader and HCM Spreadshee Spreadsheett Data Loader. Users can override the HCM Spreadsheet Data Loader default values in spreadshee spreadsheett templates.

Availability Parameters Enable Audit Data Specifies whether audit data is captured for business objects loaded using HCM Data Loader. If you set this parameter to Yes, then audit must also be enabled for Oracle Fusion Applications. Applications.

You can set this parameter parameter separately for HCM HCM Data Loade Loaderr and HCM Sp Spreadsheet readsheet Da Data ta Loader. Default Value: No Enable Load Group Size Calculation

Specifies whether the load-group size is to be calculated automatically. Set to Yes to enable the optimal load-group size to be calculated based on the number of objects to process and the available concurrent threads. When Enable Load Group Size Calculation is Yes, the Load Group Size parameter doesn't appear on the Schedule Request page. Also, the default value of the Load Group Size parameter is ignored. Default Value: Yes Enable UI Message Translation

Specifies whether messages messages on the Import and Load Data page are to appear in the language of the signed-in user. Set to Yes to enable translated messages. If this parameter is set to No, then messages appear in the language of the user who submitted the import and load request. Default Value: No HCM Data Loader Scope

Specifies whether HCM Data Loader is used for all data loading. From Release 10, the default value of the HCM Data Loader Scope parameter is Full for new customers only. You can't change this setting. For existing customers upgrading from Release 9, the default value of this parameter is Limited. If you set it to Full, then you can't change the setting back to Limited. Default Value: Full Purge Person Enabled Key

Key value supplied by Oracle Support to enable the Purge Person Data in Test Environments process. You can't enable enable and run this process in production e environments. nvironments. Default Value: None

Diagnostics Parameters Complex Error Stack Trace Occurrences by Thread

33

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

Maximum number of complex error message occurrences on a processing thread for which stack trace is recorded. Default Value: 5 Data Error Stack Trace Occurrence Occurrences s by Thread

Maximum number of data error message occurrences on a processing thread for which stack trace is recorded. Default Value: 2

File Definition Parameters Data Set Name

For data loads initiated by web service, specifies whether the Oracle WebCenter Content document title or the .zip file name is used as the data set name. Default Value: File name File Character Set

Character set used for business object and attachment files. Default Value: UTF-8 File Delimiter

A value of up to 10 characters characters used to sep separate arate attribute names on META METADATA DATA lines and and attribute va values lues on data lines. Default Value: Vertical bar (|) File Encryption

Default file encryption. Default Value: None File Escape Indicator

A value of up to 10 characters characters used to ind indicate icate that the the next character character is to be ignored on data lines. Default Value: Backslash (\) File New Line Indicator

A value of up to 10 characters characters used to ind indicate icate a new line in an attribute value. value. This value m must ust be preceded preceded by the file escape indicator. Default Value: n Flexfields Enabled

Controls whether flexfield data can be loaded. Default Value: Yes Purge Audit Data

Specifies whether audit data is to be purged automatically for objects successfully updated or deleted. Default Value: No

34

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

Note: You can’t override override the defaul defaultt value for the e enterprise. nterprise. You can can include a SET instruction instruction in individual individual .dat

files to purge audit data for the objects in the files.

Performance Parameters Days to Retain Data Sets Before Archiving

The number of days since a data set wa wass last upda updated ted before it c can an be autom automatically atically backed backed up in archive archive stage tables. tables. Qualifying data sets are backed up only if the number of data lines in the stage tables exceeds the Maximum Data Lines Before Archiving value. Default Value: 5 Days to Retain Data Sets Before Deleting

The number of days since a data set wa wass last upda updated ted before it’s automatical automatically ly and permanently permanently deleted from the stage tables. Default Value: 30 Environment Configuration

Value 1 or 2 followed by a number in the 0 through 99 that th that's at'syou suppli supplied bywhen Oracle Support. HCM Data Loadermade usesup thisofvalue toletters calculate the maximum number of range concurrent threads caned use loading data. The Data resulting maximum value is used to validate the value that you specify: • For the Maximum Concurrent Threads for Load parameter on the Configure HCM Data Loader page • When importing and loading data on the Import and Load data page • When importing and loading data using a web service In these cases, if the Maximum Concurrent Threads for Load value is higher than the calculated maximum value, value, then an error is raised. Note: You raise a service service reques requestt (SR) to obtain the value of this this parameter parameter for your environment.

If you leave the Environment Configuration parameter blank, then the default value of the calculated maximum is 1000. Default Value: None Load Group Size

Number of business objects processed as a single unit of work by a single thread. Default Value: 100 Maximum Concurrent Threads for Import

Maximum number of threads to run concurrently when importing data to the stage tables. You can set this parameter parameter separately for HCM HCM Data Loade Loaderr and HCM Sp Spreadsheet readsheet Da Data ta Loader. Default Value: 8 Maximum Concurrent Threads for Load

Maximum number of threads to run concurrently when loading data from the stage tables to the application tables.

35

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

This parameter parameter is used in conjunction wi with th the Load Group Size parameter. Only the threads required to load your objects based on the Load Group Size parameter are created. Default Value: 8 Maximum Data Lines Before Archiving

The number of data lines tthat hat can be held in the stage tables before data se sets ts are automa automatically tically backed backed up. Default Value: 10000000 Transfer Group Size

Number of file lines processed as a single unit of work by a concurrent thread. Default Value: 100000

Scheduling Default Parameters Date-Effective Update Mode

Specifies whether future-dated records should be purged when date-effective objects are loaded. You can set this parameter parameter separately for HCM HCM Data Loade Loaderr and HCM Sp Spreadsheet readsheet Da Data ta Loader. Default Value: Replace Delete Source File

Specifies whether to delete source files from fr om the Oracle WebCenter Content server once they’ve been processed. Default Value: Yes Disable Post Process Tasks

This parameter parameter is read-only. read-only. You can dis disable able individual individual postload p processes rocesses by including including a S SET ET instruction in the relevant Worker.dat or Position.dat file. Default Value: None File Action

Default file-processing action. Import and load means that valid objects are loaded automatically once import completes. Import only  means means that your

data is imported to the stage tables but load isn't initiated. Default Value: Import and load Initiate Business Object Post Processing

Specifies whether processes registered to run automatically after an object is loaded should run. You can set this parameter parameter separately for HCM HCM Data Loade Loaderr and HCM Sp Spreadsheet readsheet Da Data ta Loader. Default Value: Yes Maximum Percentage of Import Errors

Percentage of file lines in error that can occur in a business object before the import process stops for the object. Default Value: 100

36

Oracle Human Capital Management Cloud

Chapter 4

Integrating with HCM

Preparing to Use HCM Data Loader

Maximum Percentage of Load Errors

Percentage of business-object business-object instances in error that can occur for a business object before the load process stops. You can set this parameter parameter separately for HCM HCM Data Loade Loaderr and HCM Sp Spreadsheet readsheet Da Data ta Loader. Default Value: 100

Business Object Parameters: Worker You can set these parameters parameters separate separately ly for HCM Data L Loader oader and HCM Spreadsheet Spreadsheet Data Loader. Loader. Calculate Worker Full-Time Equivalent

Specifies whether the full-time equivalent (FTE) value should be calculated automat automatically ically for all worker assignments in a Worker.dat file. Default Value: No Create Worker Default Work Hour Pattern

Specifies whether a default working-hour pattern should be created automatically automatically for all worker assignments in a Worker.dat file. Default Value: No Related Topics

• The SET Instruction

HCM Data Loader Scope: Explained The HCM Data Loader Scope parameter determines which business objects objects you can load using HCM Data Loader and which other data loaders you can use use.. The parameter has two possible values, as shown in this table. HCM Data Loader Scope Value

Description

Limited

You can use HCM HCM Data Loade Loaderr to load only those business objects that aren't support supported ed by its predecessor, HCM File-Based Loader.

Full

You can use HCM HCM Data Loade Loaderr to load all supported supported business objects. You can't can't use HCM File Based Loader, which is disabled.

For customers who upgraded from an earlier release to Release 10, the default value of this parameter is Limited. While you continue to use HCM File-Base File-Based d Loader, leave HCM Data Loader Scope set to Limited. However, you should plan to use HCM Data Loader in place of HCM File-Base File-Based d Loader. To ensure complete business-object business-object support when using HCM Data Loader, you set HCM Data Loader Scope to Full. For new customers, the default value of this parameter has been Full since Release 10. Note: You can't change change HCM Data Loader Scope from Full to Limited.

37

Oracle Human Capital Management Cloud

Chapter 4

Integrating with HCM

Preparing to Use HCM Data Loader

Restricted Objects If HCM Data Loader Scope is set to Limited, then you can't load the objects shown in the following table using HCM Data Loader. You can load them using HCM Data Loader only if HCM Data Loader Scope is set to Full.

Module

Business Object

Business Object Translation

Absence Management Management

Person Absence Entry

Not applicable

Absence Management Management

Person Entitlement Detail

Not applicable

Compensation

Salary

Not applicable

Compensation

Salary Basis

Not applicable

Global HR

Actions

Actions Translation Translation

Global HR

Action Reasons Reasons

Action Reasons Reasons Translation

Global HR

Content Item

Content Item Translation, Content Item Rating Description Translation

Global HR

Content Items Relationship

Not applicable

Global HR

Department Tree

Not applicable

Global HR

Department Tree Node

Not applicable

Global HR

Education Establishment

Education Establishment Translation

Global HR

Grade

Grade Translation, Grade Step Translation

Global HR

Grade Ladder

Grade Ladder Translation, Step Rate Translation

Global HR

Grade Rate

Grade Rate Translation

Global HR

Job

Job Translation

Global HR

Job Family

Job Family Translation

Global HR

Location

Location Translation

Global HR

Organization

Organization Translation

Global HR

Person Contact

Not applicable

38

Oracle Human Capital Management Cloud

Chapter 4

Integrating with HCM

Preparing to Use HCM Data Loader

Module

Business Object

Business Object Translation

Global HR

Person Contact Relationship

Not applicable

Global HR

Position

Position Translation

Global HR

Rating Model

Rating Model Translation, Rating Category Translation, Rating Rating Level Tra Translation nslation

Global HR

Talent Profile

Talent Profile Translation Translation

Global HR

Worker

Not applicable

Global Payroll

Element Entry

Not applicable

If you try to load data for a business object that isn't supported in Limited mode, then your whole data set fails to process.

Using HCM Spreadsheet Data Loader The version of HCM Spreadshee Spreadsheett Data Loade Loaderr that you can use depends depends on the value of the HCM Data Loader Scope configuration parameter. If HCM Data Loader Scope is set to: • Full, then you can use HCM Spreadsheet Data Loader to load most objects that HCM Data Loader supports. All HCM Spreadsheet Data Loader functions are available. available. You use these tasks in the Data Exchange work area: ◦

◦

Manage Spreadsheet Templates Run Spreadsheet Data Loader

• Limited, then you can use the version of HCM Spreadsheet Spreadsheet Data Loader that was available in Release 11 and earlier. This version provides a static list of predefined spread spreadsheets. sheets. You use these tasks in the Data Exchange work area: ◦

◦

Initiate Spreadsheet Load Load Spreadsheet Data

Note: Spreadsheet data loaders other than HCM Spreadshee Spreadsheett Data Loader are unaffected by the setting of the HCM Data Loader Scope configuration parameter. For example, you can use the payroll batch loader regardless of the value of HCM Data Loader Scope.

Defining Referenced Objects: Explained Business objects that you're loading may reference a few business objects that you can't load using HCM Data Loader because they're not integration enabled. enabled. You define or review these objects in the target Oracle HCM Cloud environment before you load data that references them. You may have performed this step during implementation of Oracle HCM Cloud.

39

Oracle Human Capital Management Cloud

Chapter 4

Integrating with HCM

Preparing to Use HCM Data Loader

This table identifies identifies the main object objectss of this type. It lists the tasks tasks that you use to manage them them and the functional area to which each task belongs in the Setup and Maintenance work area.

Business Object

Functional Area

Task

Application Reference Reference Data Set Set

Enterprise Profile

Manage Reference Data Sets

Assignment Status Type

Workforce Information

Manage Assignment Status

Business Unit

Organization Structures

Manage Business Unit

Content Type

Workforce Profiles

Manage Profile Content Types

Currency Code

Financial Reporting Structures

Manage Currencies

Element Type

Elements and Formulas

Manage Elements

Legal Entity

Legal Structures

Manage Legal Entity

Official Language Code

Application Extensions Extensions

Manage Languages

Profile Type

Workforce Profiles

Manage Profile Types

Schedule

Workforce Information

Manage Work Schedules

.

Foreign-Object References When you refer to these objects from objects that you're 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 identifies identifies the user key that you can use for foreign-object references. references. For example, the Position object includes a reference to the Business Unit object, which isn't integration enabled. The position documentation identifies the business-unit business-u nit name as its user key. Therefore, when loading a Position object, you can refer to the associated business unit using the business-unit name. To see the supplied documentation documentation for a business object, click the object name on the View Business Objects page.

Reviewing Lists of Values: Explained The permitted values of ma many ny object attributes attributes are defi defined ned in lists of values. Some lists of values are predefined predefined and can't can't be updated in any way. Others contain some values, but you can also add your own. In some cases, you can edit or remove predefined values. In Oracle HCM Cloud, lists of values are defined as lookup types. You're recommended to review the predefined lookup types 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.

40

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

Reviewing Lookup Types To manage lookup lookup types, perform relevant tasks in the Setup and Maintena Maintenance nce work area. area. For example, example, the Workforce Information functional area contains tasks for managing many lookup types, including person lookups, termination lookups, document lookups, and checklist lookups. To manage person lookup types, perform the Manage Person Lookups task. On the Manage Person Lookups page, select a lookup type to edit. The list includes: • Address types types • Contact relationships • Ethnicity • Highest education level • Honors • Marital status • Military rank • Phone types • Religion Ensure that the defined lookup values support the data that you're planning to load. Related Topics

• Lookups: Explained

Defining the Source-System Owner: Procedure If you plan to use source keys, then you must add your source-system owner values to the HRC_SOURCE_S YSTEM_OWNER lo lookup okup type before you load data. You must have the Application Implementati Implementation on Consultant or Human Capital Management Application Application Administrator job role or privileges to perform this task. Use the Manage Common Lookups task in the Setup and Maintenance work area. Follow these steps: 1. On the Manage Common Lookups page, search for the lookup type HRC_SOURCE_SYSTEM_OWNER. 2. In the search results, select the lookup type to display its lookup codes. 3. In the Lookup Codes section of the page, click the New icon to add a lookup-code row. 4. Complete the fields in the row. Ensure that the new code is enabled and the dates are valid for the data that you're

loading. 5. Repeat steps 3 and 4 for additional source-system owner values. 6. Click Save and Close. Related Topics

• Source Keys: Explained

41

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

Preparing to Load Workers: Points to Consider Before you load Worker objects, you must decide: • Whether you want user accounts to be created automatically automatically for those workers. • Whether user credentials are to be sent automatically to new users. • Which roles are to be provisioned automatica automatically lly to new users. User accounts created without at least one role are automatically suspended. This topic describes describes each each of these d decisions. ecisions.

Creating User Accounts Automatically The enterprise option User Account Creation controls whether user accounts are created automatically for new workers, regardless of how those workers are created. If user accounts are created automatically in your enterprise, then you can prevent accounts being created for individual workers. To prevent account creation, include the GeneratedUserAccountFlag attribute of the User Information component and set it to N. Note: If User Account Creation is set to None, then you can't override it for individual workers.

You can supply supply a user name name in the Use Userr Information component component of the Worker object object that you u upload. pload. Otherwise, Otherwise, user names names are in the default format for the default user category, as specified on the Security Console. The default user-name format is the primary work email. Any changes that you make to the default format for a user category apply to all new users in the category, regardless of how they're created. Tip: New users are added to the default user category. You can move an existing user to a different user category by setting the UserCategory  attribute attribute of the User object.

Sending User Credentials to New Users If you create user accounts automatically for uploaded workers, then you can notify the users automatically of their user names and passwords. Set the SendCredentialsEmailFlag attribute of the User Information component to Y  for for any worker who is to receive this mail. SendCredentialsEmailFlag is set to N by default. If you set SendCredentialsEmailFlag to Y  for for any worker, then you must ensure that a valid notification template is enabled for the default user category for this event. Two predefined templates exist: • The New Account Template is for notifying the user. • The New Account Manager Template is for notifying the user's manager. You can also create notifica notification tion templates. templates. Notification templates a are re managed on the Security Console. Console. Any cha changes nges made to notification templates apply to the user category.

Provisioning Roles to New Users When arole-provisioning user account is created automatically for a worker, r oles are provisioned automatically to bulk the user as specified by current rules. Confirm that appropriate roleroles mappings exist for users created by upload.

42

Oracle Human Capital Management Cloud

Integrating with HCM

Chapter 4

Preparing to Use HCM Data Loader

Note: All user accounts accounts must have at least one role to remain active. active. If approp appropriate riate role mappings mappings don't exist exist

and you're not loading roles for manual assignment, then the new user account is immediately suspended. suspended. To avoid this automatic automatic susp suspension ension of the a account, ccount, define define role mappin mappings gs for workers before you load those workers. Related Topics

• Role Mappings

Testing the HCM HCM Data Loader Loader Process Flow and Connections: Connection s: Explained In a new environment, you may want to test HCM Data Loader end-to-end processing without creating unwanted data. Once you're sure that HCM Data Loader processing and connections are working as expected, you can load your own data with confidence. This topic describes how to test HCM Data Loader end-to-end processing.

Testing End-to-End End-to-End Processing HCM Data Loader provides: • A process, Test HCM Data Loader Process Flow and Connections Object • An object, Example Object When you submit the Test HCM Data Loader Process Flow and Connections process, set the Action parameter to Test HCM Data Loader. The process: 1. 2. 3. 4. 5.

Generates a file of MERGE instructions for the Example Object Adds the ExampleObjec ExampleObject.dat t.dat file to the ExampleObject||

Integrating With HCM

Short Description

Description

Comments

We need your help!