Introduction

This tutorial explains the steps to generate and edit business object specific mapping files which can then then be imported into the Oracle Integration Cloud (OIC) to transform data into the HCM Data Loader business object file shape.

Objectives

In this tutorial you will:

  • Enable generation of mapping files.
  • Generate generic and custom mapping files.
  • Edit generated mapping files.

Prerequisites

To complete the steps in this tutorial, you'll need access to:

  • The Configure HCM Data Loader task to enable mapping file generation.
  • The View Business Objects task to generate generic mapping files.
  • HCM Data Loader to import test files and generate custom mapping files.

Access can be granted using these security entitlements:

Function security privileges

Function Security Privilege Name Privilege Code Grants Access to
Manage Configuration of HCM Data Loader HRC_MANAGE_CONFIGURATION_HCM_DATA_LOADER_PRIV The Configure HCM Data Loader task

Role Hierarchies

Role Name Role Code Grants Access to
Functional Setups User ORA_ASM_FUNCTIONAL_SETUPS_USER_ABSTRACT Setup and Maintenance
HCM Data Load ORA_HRC_HCM_DATA_LOAD_DUTY HCM Data Loader tasks with the Data Exchange work area.
Upload data for Human Capital Management file based Import HCM_DATALOADER_IMPORT_RWD The hcm/dataloader/import directory on the Oracle WebCenter Content server. Required to test your HDL files and generate custom mapping files.
Download data from Human Capital Management file based Export HCM_DATALOADER_EXPORT_RWD The hcm/dataloader/export directory on the Oracle WebCenter Content server. Required to download the mapping files.


Task 1: Enable Mapping File Generation

In this step you'll enable the generation of OIC mapping files within HCM Data Loader.

There are two methods for generating mapping files:

  • Generate complete generic business object files.

    Use the View Business Objects task to generate and download mapping files describing complete business object hierarchies.

  • Generate custom business object files.

    Import and Load test files to confirm your file shape whilst generating a mapping file in the shape of your imported file.

To enable generation of mapping files:

  1. Log into the Oracle HCM Cloud application.
  2. Navigate to My Enterprise > Setup and Maintenance.
  3. Select the HCM Data Loader functional area.
  4. Click the Configure HCM Data Loader task.
    5. Click the HCM Data Loader task within the HCM Data Loader functional area.

  5. Search for the Generate Business Object Mapping Files parameter.
    6. Use the Query By Example field to search for the parameter.

  6. Set Override to Yes.

    7. There are two Override options available when enabling the generation of mapping files:

    Override Value Description
    Custom only Enables the ability to generate mapping files for business object dat files you upload with HCM Data Loader.
    Yes Enables generic mapping files to be generated from the View Business Objects task in addition to custom files.

  7. Click Save.

Tip:

For more information search for Generate Business Object Mapping Files in the HCM Data Loader Configuration Parameters topic.


Task 2: Generate Complete Mapping Files

In this step you'll generate a mapping file for a complete business object hierarchy.

  1. Log into the Oracle HCM Cloud application.
  2. Navigate to My Client Groups > Data Exchange > View Business Objects.
  3. Search for and select the Document Record business object and click Refresh Object.
    4. Use the query by example to search for Document Recor and click Refresh Object

  4. Refresh the table content until the Integration Mapping File column displays a download file icon for the Document Record business object.
    5. Refresh the table until the download file icon appears for the Document Record object.

  5. Click the file download icon, the mapping file will be downloaded.

Note:

You'll edit this file in Task 4.


Task 3: Generate Custom Mapping Files

This is the recommended approach to generating mapping files for OIC. You first create a HCM Data Loader file in the shape you want your OIC integration to generate files in. This has the advantage of testing that the HDL file shape is correct before you build your integration.

  1. Define an HDL business object file. You can download the Worker Mapping File.zip file for the purposes of this tutorial.
  2. Log into the Oracle HCM Cloud application.
  3. Navigate to My Client Groups > Data Exchange > Import and Load Data.
  4. Click Import File.
  5. Drag the downloaded Worker Mapping File.zip to the Choose File button and click Review Parameters.
    6. Select the source file and click Review Parameters

  6. Check the Generate Business Object Mapping File checkbox.
    7. Check the Generate Business Object Mapping File checkbox

  7. Click Submit.
  8. Click OK to dismiss the Submitted confirmation window.
  9. Refresh the Data Sets table until your test file is seen.
  10. Occasionally, refresh the Business Objects table for your data set, until Import is complete.
  11. Click Download Mapping File on the Business Objects table toolbar to download your custom mapping file.

    This button is enabled once the business object file is imported.

    12. Click the Download Mapping File button

Tip:

If you have any import errors, it's likely that the shape of the file is incorrect. Review and correct any errors and download your mapping file only when you've successfully imported your test file.


Task 4: Editing Mapping Files

You can edit the mapping files generated by HCM Data Loader. In this task you’ll edit the Document Record mapping file you generated in Task 2.

Understand the File Shape

  1. Open the DocumentsOfRecord.nxsd file you generated in Task 2.
  2. Review the file content. All mapping files follow the same structure; there are 3 types of element groups:
    • ObjectFileData group

      There will be one ObjectFileData group, found at the top of the file. For each business object in the hierarchy this group includes an ObjectLabel element and an Object element:

      • The ObjectLabel element defines the METADATA line.
      • The Object element defines the MERGE (data) line.

      Tip:

      The formatting for the lines is also defined.

    • ObjectLabel group

      There is an ObjectLabel group for every business object in the object hierarchy. The ObjectLabel group includes elements to define the names of the attributes available to the business object. When OIC generates a file using this mapping, the attribute names (and terminators) are appended to the ObjectLabel element defined in the ObjectFileData group above.

    • Object group

      There is an Object group for every business object in the object hierarchy. The Object group includes elements to map the values of the attributes available to the business object. When OIC generates a file using this mapping, the attribute values (and terminators) are appended to the Object element defined in the ObjectFileData group above.

  3. Review the ObjectFileData group DocumentOfRecordFileData.

    4. The DocumentsOfRecord business object hierarchy has two objects: DocumentOfRecord and DocumentAttachment. An ObjectLabel element and Object element are generated for each business object in the hierarchy:


  4. Review the ObjectLabel group DocumentOfRecordsLabel.

    5. This group includes an element to define the name of each attribute available to the DocumentsOfRecord business object, including any deployed flexfield segment attributes.


    Note:

    The complete group is too large to display here.
  5. Review the Object group DocumentOfRecord.

    6. This group includes an element to map the values of each attribute available to the DocumentsOfRecord business object.


    Tip:

    The order of the attributes in the ObjectLabel and Object groups for the same business object must match.
  6. Review the ObjectLabel group DocumentAttachmentLabel.

    7. This group includes an element to define the name of each attribute available to the DocumentAttachment business object.


  7. Review the Object group DocumentAttachment.

    8. This group includes an element to map the values of each attribute available to the DocumentAttachment business object.


Edit the DocumentOfRecord Shape

OIC requires that you provide a value for every attribute defined by elements in the mapping file. If you don't need attributes in your generated HDL file, remove both elements for the attribute from the ObjectLabel and Object groups.

  1. Delete the elements from both the DocumentsOfRecordLabel and DocumentsOfRecord groups for all attributes except these:
    • DocumentName
    • DocumentCode
    • PersonNumber
    • DocumentType
  2. Reorder the elements in these groups, so that they appear in this attribute order:
    • PersonNumber
    • DocumentType
    • DocumentCode
    • DocumentName

    Note:

    The last element in the group has a different terminatedBy value. Most elements are terminated by the pipe character, the last is terminated by an end of line character. When editing your file ensure your last element in each group has the end of line terminator.

    Tip:

    The order of the elements in these groups determines the order the attributes are included in the file generated by OIC. For example, this structure will generate this METADATA line: 
    METADATA|DocumentsOfRecord|PersonNumber|DocumentType|DocumentCode|DocumentName

Edit the DocumentAttachment Shape

  1. Delete the elements from both the DocumentAttachmentLabel and DocumentAttachment groups for all attributes except these:
    • Title
    • File
    • DataTypeCode
    • DocumentCode
    • PersonNumber
    • DocumentType
    • URLorTextorFileName
  2. Reorder the elements in these groups, so that they appear in this attribute order:
    • PersonNumber
    • DocumentType
    • DocumentCode
    • DataTypeCode
    • URLorTextorFileName
    • Title
    • File

    This will generate this METADATA line: 

    METADATA|DocumentAttachment|PersonNumber|DocumentType|DocumentCode|DataTypeCode|URLorTextorFileName|Title|File

You can now import your file into OIC to generate a HDL DocumentOfRecord.dat file.

Note:

You can remove entire business object definitions from your generated mapping files if you don't need to supply data for them. To do this ensure you remove both the ObjectLabel and Object groups for the business object, in addition to the ObjectLabel and Object elements from the ObjectFileData group.

Adding SET instructions to your file shape

You may need to include SET instructions in your business object file. The simplest way to do this is to edit the nxsd to create an element that allows you define the SET instructions within your OIC mapping.

In this step you'll edit the Worker.nxsd you generated in Task 3.

  1. Open the Worker.nxsd file you generated in Task 3 in a text editor.

    2. The WorkerFileData element should look like this:


  2. Edit this element to introduce a ref entry before the WorkerLabel reference. Add: 
    3. <element ref="tns:SetInstructions" minOccurs="0" nxsd:startsWith="">
  3. Create a new SetInstructions element immediately below the WorkerFileData element:
    4. <!-- SetInstructions -->
  <element name="SetInstructions">
      <complexType>
         <sequence>
            <element name="Instruction" type="string" nxsd:style="terminated" nxsd:terminatedBy="${eol}" />
         </sequence>
      </complexType>
   </element>

    Tip:

    This supports one SET instruction. Create additional elements, such as Instruction1, Instruction2, if you need to define multiple SET instructions within the file to be generated by OIC.


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.