Introduction

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 supplies multiple attributes, some of which are references to other objects, some are lookup validated, most are optional, while some will be required for new records and others are always required.

The View Business Objects task describes the hierarchical shape and provides attribute information for every business object supported for bulk-data loading by HCM Data Loader and HCM Spreadsheet Data Loader.

Objectives

In this tutorial, you will:

  • Review available objects, the actions they allow and the attributes they provide.
  • Generate METADATA template files.
  • Download business object overview spreadsheets.

Prerequisites

To complete this tutorial, you will need:

Task 1: Review Supported Objects

In this step you'll explore the View Business Objects page and refresh the object shapes that it displays.

  1. Log into the application with a user who has access to the View Business Objects task.
  2. Navigate to My Client Groups > Data Exchange.
  3. Click View Business Objects.
    4. The View Business Objects table which lists all supported objects

    The View Business Objects table displays all the business objects supported by HCM Data Loader.

    • The Product Area column can be used to filter the business objects to review.
    • The File Name column displays the file name to use when loading data for that business object with HCM Data Loader.
    • The Load Order column indicates the order in which you should load business object data.

      • Tip:

      You can include multiple business object data files in a single .zip file and HCM Data Loader will load them in the correct order but if you're loading objects individually, follow the load order to ensure the data that can be referenced by other objects is loaded first.
  4. Use the Query by Example fields to search for business objects that start Job.

    5. Review all objects that start with the word Job.

    You can see that there are multiple objects with that start 'Job', the Business Object, Description and Product Area will help identify which of these is for loading jobs.


Refreshing Object Shape

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

Refreshing the object shape also generates the template file and overview spreadsheet for an object. The following tasks 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.
    2. Refresh the Job business object

  2. Click Submit on the Schedule Request page.
    3. Submit the process to refresh the object.

  3. Click OK on the submission confirmation, you'll be returned to the View Business Objects table.
  4. Click Refresh until the Last Refreshed Date is today's date.

Refresh Multiple Objects

To refresh the object shapes for all objects within a specific product area:

  1. Click Refresh All Objects
    2. Submit the process to refresh all objects for a product area.

  2. Use the choice list to select the Global HR - Work Structures product area.
    3. Select the product area.

    Tip:

    Select All to refresh all supported business objects but this can take several minutes with around 350 object hierarchies to refresh.

  3. Click Submit.
  4. Click View Process Results.
    5. Click the View Process Results button.

  5. Find the entry for the Global HR - Work Structures product area.
    6. Review the submitted processes.

  6. Click Refresh until the process has completed.

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

Task 2: Understanding the Business Object Hierarchy

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

  1. Use the View Business Objects page to search for the Job business object.
  2. Click on the Job business object name to navigate to the Business Object Details page.
    3. Click the Job business object name.

  3. On the left you'll see the components in the Job business object hierarchy.
    4. Review the components in the business object hierarchy

    The job object hierarchy is a simple two-level hierarchy. Some business objects, such as Worker, have many more components across multiple levels.

  4. On the right there are three tabs:
    5. Component information tabs

    Tip:

    The Job component supports flexfield segments. The Flexfield Attributes tab is not seen for components that don't support flexfield segments.
  5. Review the information in the Component Details tab for the Job component:
    6. Review the job component details

    • Use the Description to confirm you have the correct object. Descriptions often provide guidance on how to load data for the component too.
    • Supported Actions tell you what actions you can perform. Not all objects support being deleted.
    • The Required value indicates if a record for this component is always required or required when creating a new object.
    • The Integration Object Name is useful when you're using integration keys to identify your records. You'll need to know this when extracting integration key values.
    • In addition to the hierarchical representation of the object hierarchy on the left of the page, the Parent Component shows the translated name of the parent. This is blank for the top-level component in the hierarchy.
    • If the object supports attribute values being translated the Translation Object will name the business object to use to load translations. Clicking the translation object name will open the Business Object Details page for the translation object.
    • A few objects require you to be granted an additional function security privilege in order to be able to load data for them. These security related objects will have a value of Yes for the Data Loading Restricted attribute.
    • The Date Effectivity Type specifies the type of dates used by the component. For date-effective records, the check boxes that follow indicate if you can adjust an existing effective start date or end date. For example, Job is date-effective, but the effective end date can't be adjusted and will always be the end-of-time. To 'end' a job's availability you would instead make the job inactive.
    • File Name specifies the name of the file you must supply data for this component in.
    • File Discriminator specifies the discriminator you must place on the METADATA, MERGE and if supported DELETE lines, to identify the component the file line is for.
    • Integration Keys Supported indicates whether you can provide a source key or GUID to identify records of this type.
    • Spreadsheet Loading Support indicates which users can bulk-load data for this object using HCM Spreadsheet Data Loader.
  6. Click on the Job Valid Grade component in the object hierarchy.

    7. The Job Valid Grade details are now displayed.

    Review the job valid grade component details

    As this is a child component, you can see the Parent Component is now specified.

Task 3: Reviewing Available Attributes

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

  1. Click on the Attributes tab of the Business Object Details page for the Job object.
    2. Review the attribute details

    All attributes available on the Job 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 the METADATA line within your file when uploading data.
  2. Scroll down to the ActiveStatus attribute.
    • The Required status shows that this attribute must be supplied when creating new records.
    • The Lookup column names the lookup type used to validate this attribute.

      • Tip:

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

      Note:

      When supplying values for lookup validated attributes you can supply either the lookup code or the meaning. It's recommended that you supply the lookup code as this isn't translated. When you supply translated values such as lookup meanings you need to supply them in the base language for your environment, usually US, as it's the elevated user that is used to load your data, not the session user.

Task 4: Uniquely Identifying Records

  1. Click on the Job Valid Grade component in the object hierarchy.
  2. Search for the attribute that has a Key Type of Surrogate ID.
    3. Review the attribute details

    The surrogate ID attribute uniquely identifies a record, regardless of the component or object hierarchy. 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 can supply a source key or the Fusion GUID to identify valid grades.
    • The User Key column indicates that there are two user keys available, so you can use one of these to uniquely identify your valid grades.

      • Tip:

      The Required column value of Yes indicates that either the surrogate ID, or any other supported key type is required to identify each record. If either integration key type (source key or Fusion GUID), or a user key is used, it will be converted back to the surrogate ID attribute by HCM Data Loader.

      Note:

      The Create and Load New Hires with HCM Data Loader (HDL) tutorial shows you how to create files with source keys and user keys.
  3. Click the 2 user keys link in the User Key column to display the user key details:
    4. Review the user key details

    The user key attribute combinations are displayed. This tells us that to uniquely identify a Job Valid Grade using a user key you can supply either of these combination of attributes:

    • JobCode, SetCode, GradeCode and GradeSetCode
    • JobCode, SetCode and GradeCode

    Tip:

    When only one user key combination is supported, it's displayed directly in the User Key column.
  4. Search for the attribute that has a Key Type of Parent Surrogate ID.
    5. Review the parent surrogate ID

    The parent surrogate ID attribute uniquely identifies the parent record for a child component in the object hierarchy. For this component, the parent surrogate ID attribute is JobId.

    The JobId 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, or an integration key, or the user key must be supplied to identify the parent job.

    Tip:

    The Integration Keys Supported column has a more information glyph. Click this to review which attributes to supply for both integration key types.
  5. Search for attributes that have a Key Type of Foreign Object Reference.
    6. Review the foreign surrogate ID

    The GradeId attribute provides the reference to the Grade object. This is confirmed by the Description.

    • This attribute also supports integration keys and provides two user keys to uniquely identify the grade.
    • The Required column indicates that you must supply a reference to a grade when creating new records, but this can be using the surrogate ID, an integration key, or a user key.
  6. Search for attributes with a Key Type of User Key.
    7. Review the user key attributes

    These are the attributes that are included in the user keys for the surrogate ID, parent surrogate ID and foreign surrogate ID 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, such as the source key or surrogate ID value.

Task 5: Reviewing 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. In the Business Objects Details page, select the Job Legislative Extra Information component in the object hierarchy.
  2. Click on the Flexfield Attributes tab.
    3. Review the user key attributes

    The attributes for the specified Category and Context are displayed.

  3. Select a Category of Job Legislation Data and a Context of United States Job Information. Click Search.
  4. Search for the attribute that starts FLEX.
    Review the flexfield context attribute

    The FLEX:{flexfield code} attribute is always needed 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.
    6. Review the flexfield category attribute

    The EFF_CATEGORY_CODE attribute is always needed 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:
    7. Review the flexfield segment attributes

    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. Use the Manage Value Sets task to review the value set used to validate the flexfield segment and identify valid values.


Task 6: Understanding Source Reference Attributes

Data loaded by HCM Data Loader is held in generic staging tables, the values supplied for a business object will not always be stored in the same database column.

WARNING:

You should not attempt to read data directly from the HDL staging tables. Instead, supply attribute values that you want to report, total, or reconcile on, to the source reference attributes.

Source reference attributes are displayed in the Object Status page of the Import and Load Data user interface and can be extracted using HCM Extracts and OTBI reporting.

  1. On the Business Object Details page click the Attributes tab.
  2. Search for attributes that have a label starting Reference.
    3. Review the source reference attributes

    There are 10 reference attributes and a single reference context attribute.

    Tip:

    These attributes are common across all business object components supported by HCM Data Loader.

    In the METADATA line you specify prompts for each of your source reference columns using this format: 

    SourceRefTableName={context value}|SourceRef001={source-column-001}|SourceRef002={source-column-002}|SourceRef003={source-column-003}

    For example: 

    METADATA|ElementEntry|...|SourceRefTableName=ElementEntry|SourceRef001=PersonNumber|SourceRef002=ElementName|SourceRef003=Amount
MERGE|ElementEntry|...||892334|Travel Allowance|200

    Don't supply a value for the SourceRefTableName attribute, this attribute allows you to supply a context for the reference attributes in the METADATA line only.

Task 7: Downloading METADATA Template Files

When you supply data to be bulk-loaded using HCM Data Loader, your file must use the name defined for the business object and 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 includes all METADATA lines for the business object hierarchy.

  1. On the View Business Objects page, select the Job business object and click the file download icon in the Template File column.
    2. Download the METADATA template file

    A file named for the business object will be downloaded, in this case Job.dat.

  2. Open the downloaded file, it will look something like this:
    3. COMMENT Data for Business Object: Job Version: V2 Created on: 16-08-2023 
METADATA|Job|FLEX:PER_JOBS_DFF|FBLJG(PER_JOBS_DFF=Global Data Elements)|_ATT1_UK_001_SIMPLE(PER_JOBS_DFF=Global Data Elements)|_job_global(PER_JOBS_DFF=Global Data Elements)|dffCol1(PER_JOBS_DFF=Global Data Elements)|ghrJobBpad87211(PER_JOBS_DFF=Global Data Elements)|ghrJobBpad87212(PER_JOBS_DFF=Global Data Elements)|incrDffCol2(PER_JOBS_DFF=Global Data Elements)|jobAttr1(PER_JOBS_DFF=Global Data Elements)|jobglobal(PER_JOBS_DFF=Global Data Elements)|FBLJL(PER_JOBS_DFF=JobContext1)|joblocal(PER_JOBS_DFF=JobContext1)|zperJobSegment(PER_JOBS_DFF=ZPER_JOB_CONTEXT)|JobId|JobCode|JobFamilyId|ActiveStatus|FullPartTime|JobFunctionCode|ManagerLevel|MedicalCheckupRequired|StandardWorkingHours|StandardWorkingFrequency|StandardAnnualWorkingDuration|AnnualWorkingDurationUnits|RegularTemporary|BenchmarkJobFlag|BenchmarkJobId|ProgressionJobId|SetId|EffectiveStartDate|EffectiveEndDate|Name|ApprovalAuthority|SchedulingGroup|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|_EVC(PER_EVALUATION_CRITERIA_DFF=Global Data Elements)|JobId|DateEvaluated|Knowhow|Accountability|EvaluationSystem|JobEvaluationId|MeasuredIn|ProblemSolving|WorkingConditions|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|jobEffSegment1(PER_JOBS_EIT_EFF=job-eff-context)|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)|seg1(PER_JOBS_LEG_EFF=Context1)|seg2(PER_JOBS_LEG_EFF=Context2)|_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)|eeo4Category(PER_JOBS_LEG_EFF=HRX_US_JOBS)|eeo4Category_Display(PER_JOBS_LEG_EFF=HRX_US_JOBS)|eeo4Function(PER_JOBS_LEG_EFF=HRX_US_JOBS)|eeo4Function_Display(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:

    You should remove METADATA lines for components you're not including in your file and remove attributes from the remaining METADATA lines that you're not supplying values for.


Task 8: Generating Object Hierarchy Overview Spreadsheets

The overview spreadsheet supplies the same information as the View Business Objects user interface, but in a spreadsheet format. This can be useful for reviewing the business object shape offline and allows you to search for attributes across components.

  1. On the View Business Objects page, select the Job business object and click the file download icon in the Overview column.
    2. Download the overview spreadsheet

    A file named GenericBusObjectDetails.xlsx will be downloaded.

    Tip:

    If a file with this name already exists in your Downloads folder, the name will be appended with a number to make it unique.
  2. Open the downloaded file, you will be asked if you want to connect:
    Do you want to connect

  3. Click Yes.
  4. Log in with your application username
  5. Review the information on the Hierarchy Details worksheet:
    6. Review the hierarchy details worksheet

  6. Click on the Attributes worksheet. The list of supported attributes across all components in the object hierarchy will be downloaded.
    7. Review the attribute details worksheet

  7. Click on the Flexfield Attributes worksheet. If the object hierarchy supports loading into flexfield segments, the list of attributes will be downloaded.
    8. Review the flexfield attributes worksheet

Tip:

You can edit and locally save this spreadsheet. To keep your edits though, don't log in when you next open the spreadsheet.

Next Steps

The following tutorials will further expand your HCM Data Loader knowledge:

Acknowledgements

  • Authors - Ema Johnson (Senior Principal Product Manager)

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.