Oracle by Example brandingUnderstanding HCM Data Loader Business Objects

section 0Before You Begin

This 20-minute tutorial shows you how to understand the business objects supported by HCM Data Loader (HDL) and HCM Spreadsheet Data Loader (HSDL).

Background

Oracle HCM Cloud business objects can be complex and are usually hierarchical, allowing for multiple child records to exist for a business object. Each component within a business object hierarchy will provide multiple attributes, some of which are references to other objects, some are lookup validated, some will be required for new records, whilst others are always required.

The View Business Objects task is a data dictionary for the business objects supported for bulk-data loading by HCM Data Loader and HCM Spreadsheet Data Loader.

This tutorial explains how to use the View Business Objects user interface to understand how to successfully bulk-load data.

What Do You Need?

  1. Access to the View Business Objects task. For this you need the following functional security privileges:
    Name Provides Access To
    Review HCM Data Loader Business Objects View Business Objects task.
    Generate HCM Data Loader Templates Generate template files containing the METADATA lines for an object hierarchy.
    Manage Data Exchange Work Area Data Exchange work area.

    Note: The job role Human Capital Management Integration Specialist inherits all the security access required to access the View Business Objects task.

  2. A Windows machine with the Desktop Integrator installed. This is only required if you wish to downlaod the object hierarchy definition to a spreadsheet.

    Download the Desktop Integrator from the Tools menu in the application. The Desktop Integrator is not available on the Mac operating system.

section 1Reviewing Supported Objects

  1. In the application, on the home page, click My Client Groups > Data Exchange.
  2. Click View Business Objects.
    View Business Objects
    The View Business Objects table displays all the business objects supported by HCM Data Loader.
    • The File Name column displays the name of the file you must use when supplying data for that object.
    • The Load Order column indiciates the order in which you should load data for the object.

    Tip: You can provide multiple business object files in the same .zip file and HCM Data Loader will load them in the correct order.

  3. Use the Query By Example fields to search for business objects that start with 'job'.
    Search for job

    You can see that there are multiple objects with that start 'Job', the description will help identify which of these is used for loading jobs.

    Tip: You can restrict your search by the product area too.

Refreshing Object Shape

If you have configured flexfield attributes, or if the Last Refreshed date for your object is out of date, it is recommended that you refresh the object, so as to see that latest shape and attributes.

Refreshing the object shape also generates the template file, mapping file and overview spreadsheet for an object. The following sections in this tutorial will explain what these are and how to access them.

In this step, you will refresh an individual object, then refresh all objects in a specific product area.

  1. Select the Job business object record and click Refresh Object.
    Refresh the Job object
  2. Click Submit on the Schedule Request page.
    Click Submit

    Click OK on the submission confirmation, you will be returned to the View Business Objects table.

  3. Click Refresh until the Last Refreshed date is today's date.
  4. To refresh all objects, or all objects for a specific product area, click Refresh All Objects.
    Click Refresh All Objects
  5. Use the choice list to select the Global HR - Work Structures product area.
    Select Global HR - Work Structures

    Click Submit.

  6. Click View Process Results.
    Click View Process Results

    The Process Results table displays the results of all refresh object processes:

    View Process Results

    The Status indicates when the process is complete, but you can also use the Last Refreshed column in the View Business Objects table to determine when the object was refreshed last.

section 2Understanding the Object Shape

Before you can successfully load data for your objects, you need to understand the object hierarchical shape and identify which components in the object hierarchy you want to load data for.

  1. If you have closed the View Business Objects page, you will need to reopen it.
    • From the home page, click My Client Groups > Data Exchange.
    • Click View Business Objects.
  2. Search for the Job business object and click the Job business object name.
    Click the Job business object name

    You'll be navigated to the Business Object Details page.

  3. On the left you'll see the object hierarchy:
    Business Object Hierarchy

    Note: The Job object hierarchy is very simple 2-level hierarchy. Some objects, such as Worker have many more components across 5 levels.

  4. On the right there are three tabs:
    Three tabs

    Clicking on a component in the object hierarchy will display the information for that component on the tabbed pages.

    Note: The Job component supports flexfield segments. The Flexfield Attributes tab is not seen for components that do not support flexfield segments.

  5. Review the information in the Component Details tab for the Job component:
    Job details

    This tab provides useful information about the component:

    • Use the Description to confirm you have the correct object. Descriptions often provide guidance on how to load data for the component.
    • Supported Actions tell you what actions you can perform, not all objects support being deleted.
    • The Integration Object Name is useful when you are using integration keys. You'll need to know this when extracting integration key values.
    • In addition to the hierarchical representation of the object on the left of the page, the Parent Component provides the translated name of the parent. This is blank for the top level component in the hierarchy.
    • The Date Effectivity Type specifies the type of dates used by the component. For date-effective records, the following check boxes indicate if you can adjust an existing effective start date or end date. For example, for Job, you would make the job inactive, the effective end date will always be the end-of-time, so you can't adjust this.
    • File Name specifies the name of the file you must supply data for this record type in.
    • File Discriminator specifies the discriminator you must place on the METADATA, MERGE and if supported DELETE lines, to identify the record type the file line is for.
    • Integration Keys Supported indicates whether you can provide a source key or GUID to identify records of this type.

    Note: The file discriminator is sometimes the same as the Integration Object Name for the component, but not always. You must supply the file discriminator to identify records of this type in your file.

    Tip: If a translation object is named, clicking the name will navigate you to the details for that object.

  6. Click on the Job Valid Grade component in the object hierarchy.
    Click Job Valid Grade

    The Job Valid Grade details are now displayed.

    As this is a child object, you can see the Parent Component indicates that the Job component is the parent, and that valid grades are not translated.

section 3Understanding the Supported Attributes

In this step, you will learn to interpret the information provided for attributes.

  1. If you have closed the View Business Objects page, you will need to reopen it.
    • From the home page, click My Client Groups > Data Exchange.
    • Click View Business Objects.
  2. Search for the Job business object and click the Job business object name.
  3. Click on the Job Valid Grade component in the object hierarchy.
    Click on Job Valid Grade
  4. Click on the Attributes tab.
    All attributes supported by the Job Valid Grades component are displayed.
    • Each attribute has a label and description, which are displayed in your session language.
    • The attribute name is the value that you must include in your file when uploading data.
  5. Search for the attribute that has a Key Type of Surrogate ID.

    This attribute uniquely identifies records for this component, look across the columns to understand what other key types are supported.

    • The Integration Keys Supported column confirms that integration keys are supported, so you could supply your source key to identify the valid grades.
    • The User Key column indicates that 2 user keys are available, so you could use one of these to identify your valid grades.

    Tip: The Required column value of Yes indicates that either the surrogate ID, or an integration key, or one of the user keys must be supplied.

    Note: The Creating and Loading Files with HCM Data Loader (HDL) tutorial shows you how to load files with these key types.

  6. Click the 2 user keys link in the User Key column.

    The user keys attribute combinations are displayed. Click OK to close this window.

    Tip: When only one user key is supported, the attributes for it are displayed directly in the User Key column.

  7. Search for the attribute that has a Key Type of Parent Surrogate ID.

    This attribute uniquely identifies the parent job for the valid grade record.

    This attribute also supports integration keys and the User Key column lists the attributes that form the user key.

    Tip: The Required column value of Yes indicates that either the surrogate ID of the parent job, or an integration key, or the user key must be supplied.

  8. Search for attributes that have a Key Type of Foreign Object Reference.

    The GradeId attribute provides the reference to the Grade object. This is confirmed by the Description, but also the Integration Object Name.

    This attribute also supports integration keys, and provides 2 user keys to uniquely identify the grade.

    Tip: The Required column value of For new records indicates that either the surrogate ID, or an integration key, or one of the user keys must be supplied when creating valid grades.

  9. Search for attributes that have a Key Type of User Key.

    These are the attributes that are listed in the user keys of the surrogate ID, parent surrogate ID and foreign object reference attributes.

    Tip: The Required column value may be No for most user keys because you may supply another key type to identify the record being referenced.

  10. Click on Job Evaluation in the object hierarchy. The attributes for this component are displayed.

    When an attribute is lookup validated, the lookup type is listed. Here you can see that the attribute EvaluationSystem is validated by the EVAL_SYSTEM lookup type.

    Tip: Use the Manage Common Lookups task to review the list of values for the attribute.

section 4Understanding Flexfield Attributes

In this step you'll learn how to interpret the information provided for flexfield attributes.

Tip: The Flexfield Attributes tab is only seen when the component selected in the object hierarchy supports flexfield segments.

  1. If you have closed the View Business Objects page, you will need to reopen it.
    • From the home page, click My Client Groups > Data Exchange.
    • Click View Business Objects.
    • Search for the Job business object and click the object name.
  2. In the Business Objects Details page, select Job Legislative Extra Information in the component hierarchy.
  3. Click on the Flexfield Attributes tab.
    The attributes for the specified category and context are displayed.

    To review the attributes for a specific category and context use the choice lists and click Search.

  4. Search for the attribute that starts FLEX.

    The FLEX:{flexfield code} attribute is always required when you supply data for any flexfield segment.

    • The attribute name tells HDL which flexfield code data is being supplied for. For example, PER_JOBS_LEG_EFF.
    • For each data line containing flexfield segments, you supply this attribute with the flexfield context code of the data supplied on the line.

      Tip:The value to use is shown to the right of the Context choice list, for example, HRX_US_JOBS.

  5. Search for the attribute that starts EFF.
    The EFF_CATEGORY_CODE attribute is always required when you supply data for extensible flexfield segments. You supply the extensible flexfield category code to this attribute, such as JOB_LEG.

    Tip: Descriptive flexfields don't have categories so this field isn't available for descriptive flexfields.

  6. Review the other attributes listed:
    Flexfield attribute names always have a hint, in the format: 
    {flexfield attribute name}({flexfield code}={context code})
    For example, _EEO1_CATEGORY(PER_JOBS_LEG_EFF=HRX_US_JOBS). This format tells HDL that the EEO1 Category segment belongs to the PER_JOBS_LEG_EFF flexfield in the HRX_US_JOBS context.

    Some flexfield segments offer two attributes, one that accepts a code, the other accepts the meaning, or display value. The attributes that accept the display value will always have the format: 

    {flexfield attribute name}_Display({flexfield code}={context code})
    For example, _EEO1_CATEGORY_Display(PER_JOBS_LEG_EFF=HRX_US_JOBS).

    Tip: For lookup validated flexfield segments, it is recommended that you supply the code value to the base attribute, to avoid translation issues.

    Tip: Use the Manage Value Sets task to review the value set used to validate the flexfield segment and identify the valid values for the segment.

The Loading Flexfield Data chapter of the Integrating with HCM guide provides more detail on how to load data for flexfield segments.

section 5Downloading Generated Templates

When you supply data to be bulk-loaded using HCM Data Loader, your file must have the name defined for the business object, which must include METADATA lines for the components and attributes you are supplying data for.

Instead of generating this manually, you can download a template file which provides all METADATA lines for the business object hierarchy.

  1. On the View Business Objects page, select the business object of interest and click the file download icon in the Template File column.

    A file named for the business object will be downloaded, such as Job.dat.

  2. Open the downloaded file, it will look something like this: 
    COMMENT Data for Business Object: Job Version: V2 Created on: 09-07-2020 
METADATA|Job|FLEX:PER_JOBS_DFF|jobAttr1(PER_JOBS_DFF=Global Data Elements)|JobId|JobCode|JobFamilyId|ActiveStatus|FullPartTime|JobFunctionCode|ManagerLevel|MedicalCheckupRequired|RegularTemporary|BenchmarkJobFlag|BenchmarkJobId|ProgressionJobId|SetId|EffectiveStartDate|EffectiveEndDate|Name|ApprovalAuthority|SetCode|BenchmarkJobCode|ProgressionJobCode|JobFamilyName|JobFamilyCode|ActionReasonCode|SourceSystemOwner|SourceSystemId|GUID|CategoryCode|GradeLadderId|GradeLadderName|RequisitionTemplateId|RequisitionNumber|SourceRefTableName=|SourceRef001=|SourceRef002=|SourceRef003=|SourceRef004=|SourceRef005=|SourceRef006=|SourceRef007=|SourceRef008=|SourceRef009=|SourceRef010=
METADATA|JobEvaluation|FLEX:PER_EVALUATION_CRITERIA_DFF|JobId|DateEvaluated|Knowhow|Accountability|EvaluationSystem|JobEvaluationId|MeasuredIn|ProblemSolving|JobCode|SetCode|SourceSystemOwner|SourceSystemId|GUID|SourceRefTableName=|SourceRef001=|SourceRef002=|SourceRef003=|SourceRef004=|SourceRef005=|SourceRef006=|SourceRef007=|SourceRef008=|SourceRef009=|SourceRef010=
METADATA|JobGrade|GradeId|JobId|EffectiveStartDate|EffectiveEndDate|ValidGradeId|GradeCode|SetCode|JobCode|SourceSystemOwner|SourceSystemId|GUID|GradeSetCode|SourceRefTableName=|SourceRef001=|SourceRef002=|SourceRef003=|SourceRef004=|SourceRef005=|SourceRef006=|SourceRef007=|SourceRef008=|SourceRef009=|SourceRef010=
METADATA|JobExtraInfo|FLEX:PER_JOBS_EIT_EFF|EFF_CATEGORY_CODE|EffectiveEndDate|EffectiveStartDate|InformationType|JeiInformationCategory|JobExtraInfoId|JobId|LegislationCode|SequenceNumber|SourceSystemOwner|SourceSystemId|GUID|JobCode|SetCode|SetId|SourceRefTableName=|SourceRef001=|SourceRef002=|SourceRef003=|SourceRef004=|SourceRef005=|SourceRef006=|SourceRef007=|SourceRef008=|SourceRef009=|SourceRef010=
METADATA|JobLegislative|FLEX:PER_JOBS_LEG_EFF|EFF_CATEGORY_CODE|_EEOG(PER_JOBS_LEG_EFF=CA)|_EEOG_Display(PER_JOBS_LEG_EFF=CA)|_NOC_CODE(PER_JOBS_LEG_EFF=CA)|_NOC_CODE_Display(PER_JOBS_LEG_EFF=CA)|employmentEquityEligible(PER_JOBS_LEG_EFF=CA)|employmentEquityEligible_Display(PER_JOBS_LEG_EFF=CA)|_POSITION_TYPE(PER_JOBS_LEG_EFF=CH)|_POSITION_TYPE_Display(PER_JOBS_LEG_EFF=CH)|_ECAP_JOB(PER_JOBS_LEG_EFF=FR)|_ECAP_JOB_Display(PER_JOBS_LEG_EFF=FR)|_INSEE_PCS_CODE(PER_JOBS_LEG_EFF=FR)|_INSEE_PCS_CODE_Display(PER_JOBS_LEG_EFF=FR)|_INSEE_PCS_EXT_CODE(PER_JOBS_LEG_EFF=FR)|_INSEE_PCS_EXT_CODE_Display(PER_JOBS_LEG_EFF=FR)|_EEO1_CATEGORY(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_EEO1_CATEGORY_Display(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_FLSA_STATUS(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_FLSA_STATUS_Display(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_JOB_GROUP(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_JOB_GROUP_Display(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_LINE_OF_PROGRESSION(PER_JOBS_LEG_EFF=HRX_US_JOBS)|standardOccupationalClassifica(PER_JOBS_LEG_EFF=HRX_US_JOBS)|_ORA_HRX_BR_JOBS_CBO(PER_JOBS_LEG_EFF=ORA_HRX_BR_JOBS)|_ORA_HRX_BR_JOBS_CBO_Display(PER_JOBS_LEG_EFF=ORA_HRX_BR_JOBS)|oraHrxCaWcJobClUnit(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|oraHrxCaWcJobClUnit_Display(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|oraHrxCaWcJobProv(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|oraHrxCaWcJobProv_Display(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|oraHrxCaWcJobPsu(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|oraHrxCaWcJobPsu_Display(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|oraHrxCaWcJobUniqueSeg(PER_JOBS_LEG_EFF=ORA_HRX_CA_WC_JOBS)|_ORA_HRX_MX_SI_SALARY_TYPE(PER_JOBS_LEG_EFF=ORA_HRX_MX_JOBS)|_ORA_HRX_MX_SI_SALARY_TYPE_Display(PER_JOBS_LEG_EFF=ORA_HRX_MX_JOBS)|perjobmrnuk(PER_JOBS_LEG_EFF=PER_JOB_TEST_MR)|perjobmruk(PER_JOBS_LEG_EFF=PER_JOB_TEST_MR)|JobId|JobLegId|EffectiveStartDate|EffectiveEndDate|InformationCategory|LegislationCode|SourceSystemOwner|SourceSystemId|GUID|JobCode|SetCode|SetId|SequenceNumber|SourceRefTableName=|SourceRef001=|SourceRef002=|SourceRef003=|SourceRef004=|SourceRef005=|SourceRef006=|SourceRef007=|SourceRef008=|SourceRef009=|SourceRef010=

    Note: It is recommended that you remove any METADATA lines for components you don't supply data for. Only include the attributes you intend to supply data for.

  3. Scroll to the right of your downloaded file and you'll see attributes not shown in the Attributes table of the Business Object Details page: 
    SourceRefTableName=|SourceRef001=|SourceRef002=|SourceRef003=|SourceRef004=|SourceRef005=|SourceRef006=|SourceRef007=|SourceRef008=|SourceRef009=|SourceRef010=
    The source reference attributes allow you to repeat any attribute values that you want to report, total or reconcile.

    These attributes values are visible on the error management pages and available to download using HCM Extracts and OTBI.

Tip: Use the Review Processes page to download zip files containing all templates files for a product area you have refreshed.

section 6Downloading Object Hierarchy Overview Spreadsheet

If you have Desktop Integrator installed, you can download information about an object hierarchy into an Excel spreadsheet.

  1. On the View Business Objects page, select the business object of interest and click the file download icon in the Overview column.

    A file named GenericBusObjDetails.xlsx will be downloaded, open it.

  2. You will be asked if you want to connect, click Yes.
  3. When prompted, enter your application log in details.
  4. The Hierarchy Details tab will be populated with the component level information for the object hierarchy.

    The information provided is the same as the Component Details tab of the Business Object Details page.

  5. Click the Attributes tab.

    All attributes for the object hierarchy are listed. You can use File Discriminator column to identify which attributes are for which component in the object hierarchy.

    The information provided is the same as the Attributes tab of the Business Object Details page.

  6. Click the Flexfield Attributes tab.

    If there are configured and deployed flexfield segments for your object hierarchy, they will be seen here.

    Tip: If you can't find attributes for flexfield segments you are expecting to see, refresh the object shape before downloading the Overview spreadsheet again.

  7. If you want to keep the spreasdheet for offline use later, save it to a name of your choice.

    Tip: When you reopen the spreadsheet it will ask if you want to connect again, you can cancel this to review the data you previously saved.

more informationWant to Learn More?