An Oracle White Paper

December 2014

Oracle Fusion Human Capital Management 11g Release 9 (11.1.9)

Automating HCM Data Loader

Automating HCM Data Loader

Introduction ....................................................................................... 1
Oracle WebCenter Content and HCM Data Loader ........................... 2
Methods of Staging Files on the Oracle WebCenter Content
Server............................................................................................ 2
WebCenter Content Document Transfer Utility Interface ............... 5
Remote Intradoc Client (RIDC) ...................................................... 6
HCM Data Loader Integration Service ............................................. 10
Sample Code to Invoke HCMDataLoader .................................... 10

Automating HCM Data Loader

Introduction
This document describes how to integrate Oracle Fusion Human Capital Management (HCM)
11g Release 9 (11.1.9) HCM Data Loader with Oracle WebCenter Content, to provide the
ability to automate the bulk loading of data into HCM.
WebCenter Content is the staging mechanism for files to be loaded and processed by HCM
Data Loader. The following two topics are covered:

The available methods for staging a zip file on the WebCenter Content server for
consumption by HCM Data Loader.

How to invoke the web service to consume and process the staged zip file.

See the HCM Data Loader Users Guide (My Oracle Support document ID 1664133.1) for
general information about HCM Data Loader and instructions for constructing the zip file
containing data to be loaded.

Automating HCM Data Loader

Oracle WebCenter Content and HCM Data Loader

WebCenter Content is the infrastructure for the staging of data files for processing by HCM Data
Loader.
WebCenter Content offers secure file-management capabilities and is used by many Oracle Fusion
Applications products.
This document reviews methods of staging a file for HCM Data Loader on the WebCenter Content
server. Once a file is staged it can be processed by invoking an externally available web service, details
of which are also provided in this document. Alternatively, you can initiate the processing using the
Oracle Fusion HCM interface described in this document.
Note: The following duty roles are required in all interactions with HCM Data Loader:

HCM Data Load Duty

(HRC_HCM_DATA_LOAD_DUTY)

File Import and Export Management Duty

(FND_FILE_IMPORT_AND_EXPORT_MANAGEMENT_DUTY)

Methods of Staging Files on the Oracle WebCenter Content Server

You can stage a zip file on the WebCenter Content server using:

The Oracle Fusion HCM File Import and Export interface

The WebCenter Content Document Transfer Utility

Remote Intradoc Client (RIDC)

Automating HCM Data Loader

File Import and Export Interface

You can stage HCM Data Loader zip files on the WebCenter Content server using the File Import and
Export task (Navigator - Tools - File Import and Export). Once the file is on the WebCenter
Content server, it is available for processing by HCM Data Loader.

Figure 1. Location of the File Import and Export Task in the Navigator

When you upload a file, set the Account value to hcm/dataload/import, to secure the file.

Figure 2. Upload a file using the File Import and Export interface

Automating HCM Data Loader

One of the parameters required for both the HCMDataLoader web service and manual processing is
the WebCenter Content ID. This ID is automatically generated when the file is loaded.
By default, the Content ID is not displayed on the File Import and Export page. You can make it
visible by setting the Search Results table to include the column. Select View - Columns - Content ID
to include the Content ID column.
Once the file is loaded, you can process it manually from the Import and Load Data page.
Processing the File Manually

To process the file manually once it is loaded:

1.

Open the Data Exchange work area (Navigator - Workforce Management - Data Exchange).

2.

In the Data Exchange work area, select the task Import and Load Data, under the HCM Data Loader
task group.

3.

On the Import and Load Data page, click Import File.

4.

In the WebCenter Content popup window, select the file with the content ID that you obtained when
loading the data file using the File Import and Export interface.

5.

Click Submit.

6.

Review the default parameter values and modify if necessary.

7.

Click Submit.

Figure 3. Manually submitting a file for processing using the HCM Data Loader interface

Automating HCM Data Loader

WebCenter Content Document Transfer Utility Interface

The WebCenter Content Document Transfer Utility for Oracle Fusion Applications is a feature-set
Java library that provides content export and import capabilities. The utility can be evaluated from the
Individual Component Downloads section of the Oracle WebCenter Content 11gR1 Downloads tab
on Oracle Technology Network (OTN):
http://www.oracle.com/technetwork/middleware/webcenter/content/downloads/index.html
(Note: Current customers download from Oracle Software Delivery Cloud.)
Open the Individual Components Download section on the Downloads tab, accept the license
agreement, and download the WebCenter Content Document Transfer Utility. Once the component
zip file is downloaded, extract the JAR file. The zip file also contains a useful readme file describing
the example invocation command shown in Figure 4.
java -classpath "oracle.ucm.fa_client_11.1.1.jar" oracle.ucm.client.UploadTool -url=https://{host}/cs/idcplg
--username=<provide_user_name> --password=<provide_password> -primaryFile="<file_path_with_filename>" --dDocTitle="<provide_Zip_Filename>" dDocAccount=hcm/dataloader/import
e.g.
java -cp "oracle.ucm.fa_client_11.1.1.jar" oracle.ucm.client.UploadTool -url="https://{host}/cs/idcplg" --username="HCM_IMPL" --password="Welcome1" -primaryFile="/scratch/HRDataFile.zip" --dDocTitle="Department Load File" -dSecurityGroup="FAFusionImportExport" --dDocAccount="hcm/dataloader/import"
Sample output:
Oracle WebCenter Content Document Transfer Utility
Oracle Fusion Applications
Copyright (c) 2013, Oracle.

All rights reserved.

Performing upload (CHECKIN_UNIVERSAL) ...

Upload successful.
[dID=21537 | dDocName=UCMFA021487]
Figure 4. Example invocation command for the WebCenter Content document transfer utility.

How to Define the WebCenter Content URL

The URL in the command line uses the same domain name as your service. To obtain the WebCenter
Content URL:
1.

Obtain the URL for Setup and Maintenance from the Service Details section in the cloud
environments provisioning email that your administrator received.
It should look like the following example: https://fs-xxxxxxxxxxx.oracleoutsourcing.com/setup/faces/TaskListManagerTop

2.

Modify this URL by removing /setup/Task and substituting it with /cs/idcplg.

Automating HCM Data Loader

The above URL would now be the following, which can be used in the command line script
example detailed in Figure 4.
https://fs-xxxxxxxxxxx.oracleoutsourcing.com/cs/idcplg
This method of defining the WebCenter Content URL also applies to the examples given elsewhere in
this document.
Other Command Line Parameters

The dDocName value (which is equivalent to the content ID) returned when executing the above
statement is required for the HCMDataLoader call described later in this document.
Review the readme file downloaded with the WebCenter Content Document Transfer Utility for a list
of all parameters, including advanced networking options for resolving proxy issues.

Remote Intradoc Client (RIDC)

The RIDC communication API removes data abstractions to Oracle Content Server while still
providing a wrapper to handle connection pooling, security, and protocol specifics. This is the
recommended approach if you want to use native Java APIs.
RIDC supports three protocols: Intradoc, HTTP, and JAX-WS.
Intradoc

The Intradoc protocol communicates with Oracle Content Server over the Intradoc socket port
(typically, 4444). This protocol does not perform password validation and so requires a trusted
connection between the client and Oracle Content Server. Clients that use this protocol are expected to
perform any required authentication. Intradoc communication can also be configured to run over SSL.
HTTP

RIDC communicates with the web server for Oracle Content Server using the Apache HttpClient
package. Unlike Intradoc, this protocol requires authentication credentials for each request.
JAX-WS

The JAX-WS protocol is supported only in Oracle WebCenter Content 11g with Oracle Content Server
running in Oracle WebLogic Server. To provide JAX-WS support, several additional JAR files are
required.
For more information, see:

Oracle WebCenter Content Developers Guide for Content Server (specifically the section Using
RIDC to Access Content Server)

Oracle Fusion Middleware Developer's Guide for Remote Intradoc Client (RIDC)

Once the RIDC Component Library download file has been unzipped, include the following JAR files
in your project. Figure 5 shows an example from Oracle JDeveloper.

Automating HCM Data Loader

Figure 5. Example showing how to include libraries in a JDeveloper project

Figure 6 shows example code for uploading a file into WebCenter Content. Parameter details are
provided in Figure 7.
import
import
import
import

java.io.File;
java.io.FileInputStream;
java.io.InputStream;
java.io.IOException;

import
import
import
import
import
import
import

oracle.stellent.ridc.IdcClient;
oracle.stellent.ridc.IdcClientException;
oracle.stellent.ridc.IdcClientManager;
oracle.stellent.ridc.IdcContext;
oracle.stellent.ridc.model.DataBinder;
oracle.stellent.ridc.model.TransferFile;
oracle.stellent.ridc.protocol.ServiceResponse;

public class UploadFile {

public static void main(String[] arg) throws Exception {
try {
IdcClientManager m_clientManager = new IdcClientManager();
IdcClient idcClient =
m_clientManager.createClient("https://{host}/cs/idcplg"); // replace with
relevant URL
IdcContext userContext = new IdcContext("HCM_ADMIN", "Password"); // replace with

Automating HCM Data Loader

relevant username password

checkin(idcClient, userContext,
"/scratch/jdoe/ridc/BusinessUnit1.zip",
// Replace with fully qualified path to source file
"Document", // content type
"BusinessUnit1", // doc title
userContext.getUser(), // author
"FAFusionImportExport", // security group
"hcm$/dataloader$/import$", // account
"BU5") // dDocName - this is the ContentId
;
} catch (IdcClientException e) {
e.printStackTrace();
}
}
/**
* Method description
*
* @param idcClient
* @param userContext
* @param sourceFileFQP
fully qualified path to source content
* @param contentType
content type
* @param dDocTitle
doc title
* @param dDocAuthor
author
* @param dSecurityGroup
security group
* @param dDocAccount
account
* @param dDocName
dDocName
*
* @throws IdcClientException
*/
public static void checkin(IdcClient idcClient, IdcContext userContext,
String sourceFileFQP, String contentType,
String dDocTitle, String dDocAuthor,
String dSecurityGroup, String dDocAccount,
String dDocName) throws IdcClientException {
InputStream is = null;
try {
String fileName =
sourceFileFQP.substring(sourceFileFQP.lastIndexOf('/') + 1);
is = new FileInputStream(sourceFileFQP);
long fileLength = new File(sourceFileFQP).length();
TransferFile primaryFile = new TransferFile();
primaryFile.setInputStream(is);
primaryFile.setContentType(contentType);
primaryFile.setFileName(fileName);
primaryFile.setContentLength(fileLength);
//
//
//
//

note!!! when using HTTP protocol (not intradoc/jaxws) - one must explicitly
set the Content Length when supplying an InputStream to the transfer file
e.g. primaryFile.setContentLength(xxx);
otherwise, a 0-byte file results on the server

DataBinder request = idcClient.createBinder();

request.putLocal("IdcService", "CHECKIN_UNIVERSAL");
request.addFile("primaryFile", primaryFile);
request.putLocal("dDocTitle", dDocTitle);

Automating HCM Data Loader

request.putLocal("dDocAuthor", dDocAuthor);
request.putLocal("dDocType", contentType);
request.putLocal("dSecurityGroup", dSecurityGroup);
// if server is setup to use accounts - an account MUST be specified
// even if it is the empty string; supplying null results in Content server
// attempting to apply an account named "null" to the content!
request.putLocal("dDocAccount", dDocAccount == null ? "" : dDocAccount);
if (dDocName != null && dDocName.trim().length() > 0) {
request.putLocal("dDocName", dDocName);
}
// execute the request
ServiceResponse response =
idcClient.sendRequest(userContext, request); // throws IdcClientException
// get the binder - get a binder closes the response automatically
DataBinder responseBinder =
response.getResponseAsBinder(); // throws IdcClientException
} catch (IOException e) {
e.printStackTrace(System.out);
} finally {
if (is != null) {
try {
is.close();
} catch (IOException ignore) {
}
}
}
}
}
Figure 6. Example java code for uploading files to Oracle WebCenter Content

Parameter

Meaning

Comment for HDL

IdcService

The service to invoke.

CHECKIN_UNIVERSAL for uploading files

dDocName

The content ID for the content item.

Value passed to HCMDataLoader

dDocAuthor

The content item author (contributor).

dDocTitle

The content item title.

The title of the file as it appears in

Import/Export UI

dDocType

The content item type.

Document

dSecurityGroup

The security group such as Public or Secure.

FAFusionImportExport

dDocAccount

The account for the content item. Required only if accounts

hcm$/dataloader$/import$

are enabled.
primaryFile

The absolute path to the location of the file as seen from the
server.

Figure 7. Attributes of the DataBinder object used in the code example

Automating HCM Data Loader

HCM Data Loader Integration Service

HCM Data Loader implements a web service that can be used to initiate the import and load of data
files staged on the WebCenter Content server. As noted earlier, you can process such data files
manually from the Import and Load Data page.
Once you have placed the zip file containing the .dat files in the WebCenter Content, secured with
account hcm/dataloader/import, the web service HCMDataLoader can be invoked to perform an
Import or Import and Load of data to Fusion.
Service invocation details for HCMDataLoader can be found in the public Oracle Enterprise
Repository (OER) http://fusionappsoer.oracle.com. Review the documentation on this site for
information about finding services and other artifacts in OER.

Sample Code to Invoke HCMDataLoader

Several ways exist of invoking Oracle Fusion web services. This section explains how to invoke web
services using generated proxy classes. You can generate your own proxy classes by providing the URL
of the service WSDL file to your generator of choice. These proxy classes are then used to invoke the
web service.
Note: Oracle Fusion Web services are protected by Oracle Web Services Manager (OWSM) security
policies. Refer to the OWSM Security and Administrator's Guide for Web Services for further details.
Figure 8 provides details of the steps required to call the HCMDataLoader.
http://{Host}/hcmCommonDataLoader/HCMDataLoader
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:importAndLoadDataAsync
xmlns:ns1="http://xmlns.oracle.com/apps/hcm/common/dataLoader/core/dataLoaderIntegratio
nService/types/">
<ns1:ContentId></ns1:ContentId>
<ns1:Parameters></ns1:Parameters>
</ns1:importAndLoadDataAsync>
</soap:Body>
</soap:Envelope>
Figure 8. Sample service interface

The URL for above is resolved slightly differently than that required for WebCenter Content given
above. You should use the domain name given for the Service Home URL which is shown in the
Service Detail section of you service provision email. Using the same example given earlier, the above
URL will be: https://hcm-xxxxxxxxxxx.oracleoutsourcing.com/hcmCommonDataLoader/HCMDataLoader?wsdl

10

Automating HCM Data Loader

Parameter
ContentId

Meaning
Content ID of the file on the WebCenter Content server (the same value as dDocName in the
WebCenter Content Java call).

Parameters

Name and value pairs. The following parameter names are available, none of these are mandatory:

ImportMaximumErrors: Percentage of file lines in error that can occur in a business object
before the import process stops.

LoadMaximumErrors: Percentage of business object instances in error that can occur for a
business object before the validation and load processes stop.

LoadConcurrentThreads: Number of concurrent threads when validating or loading.

LoadGroupSize: Number of business objects processed as a single unit of work by a

concurrent thread.

FileEncryption: Type of file encryption.

DeleteSourceFile: Y or N value. If set to Y or left blank, deletes the source file from the
WebCenterContent server once the file content has been transferred into HDL stage tables
and is no longer required.

For example:
ImportMaximumErrors=100,LoadMaximumErrors=100,LoadConcurrentThreads=4,FileEncryption=PGP
SIGNED,DeleteSourceFile=N

Figure 9. Parameters for HCMDataLoader

Implications of Security Policy on the HCMDataLoader

The HCMDataLoader web service is secured using the following policy:

oracle/wss11_saml_or_username_token_with_message_protection_service_policy
Therefore, when a client calls the service it must satisfy the message protection policy to ensure that
the payload is transported encrypted or sent over the SSL transport layer.
A client policy that can be used to meet this requirement is:
oracle/wss11_username_token_with_message_protection_client_policy
To use this policy, the message must be encrypted using a public key provided by the server. When the
message reaches the server it can be decrypted by the server's private key. A KeyStore is used to import
the certificate and it is referenced in the subsequent client code.
The public key can be obtained from the certificate provided in the service WSDL file. See Figure 10
(the certificate is Base64 encoded).

11

Automating HCM Data Loader

Figure 10. Example of a Certificate in a Service WSDL File

To use the key contained in this certificate, you need to create a local KeyStore and import the
certificate into it:
1. Create a new file with any name you like. You must change the extension to .cer to indicate that it is

a certificate file.
2. Using a text editor, open the file you just created and enter "-----BEGIN CERTIFICATE-----" on

the first line.

3. In the next line, copy the Base64 encoded certificate from the service WSDL file to the newly

created certificate file.

4. Add "-----END CERTIFICATE-----" on a new line and save the file. Now you have a certificate

containing the public key from the server.

5. Open the command line and change the directory to $JAVA_HOME/bin. Use the following

command to create a KeyStore and import the public key from the certificate.
keytool -import -file <Provide the path of the certification.cer file> -alias orakey keypass welcome -keystore <Provide the path where the jks file needs to be
created(including the file name)> -storepass welcome

6. You can find the KeyStore file in the KeyStore path you set.

Once the client KeyStore has been created, you can call the service using the proxy classes. The
following parameters are used by the proxy class to encrypt and decrypt the message.

12

Automating HCM Data Loader

Parameter
WSBindingProvider.USERNAME_PROPERTY

Description
User name of the application user who has relevant privileges for importing
and processing FBL data files.

WSBindingProvider.PASSWORD_PROPERTY

The password of the above user.

ClientConstants.WSSEC_KEYSTORE_TYPE

Type of the KeyStore you created. JKS (Java KeyStore) is widely used and is
the most common type.

ClientConstants.WSSEC_KEYSTORE_LOCATION

Path of the client KeyStore file.

ClientConstants.WSSEC_KEYSTORE_PASSWORD

Password of your client KeyStore.

ClientConstants.WSSEC_ENC_KEY_ALIAS

Alias of the key you use to decrypt the SOAP message from the server.

ClientConstants.WSSEC_ENC_KEY_PASSWORD

Password of the key you use to decrypt the SOAP message.

ClientConstants.WSSEC_RECIPIENT_KEY_ALIAS

Alias of the key you use to encrypt the SOAP message to the server.

How to Create a Proxy Class

Generate the JAX-WS proxy class for the HCMDataLoader using the wsimport command, which is
available at JAVA_HOME/bin:
wsimport -s <Provide the folder where the generated files need to be placed> -d
<Provide the folder where the generated files need to be placed> <The HCM Data Loader
Integration Service URL>

Example:
wsimport -s "D:\HCMDataLoader" -d "D:\ HCMDataLoader"

https://{host}/hcmCommonDataLoader/HCMDataLoader?wsdl

The files generated are placed in the following two folders:

com

sdo

Add the generated code to a JAR file:

zip loaderIntegrationProxy.jar -r * -

How to Invoke the Web Service

Create the client class HCMDataLoaderServiceSoapHttpPortClient for invoking the

dataloaderintegrationservice. The class must be created in the folder:
com/oracle/xmlns/apps/hcm/common/dataloader/core/dataloaderintegrationservice
package com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice;

import

13

Automating HCM Data Loader

com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLo
ader;
import
com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLo
ader_Service;
import
com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.ServiceEx
ception;

import java.util.Map;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.WebServiceRef;
import weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature;

public class HCMDataLoaderServiceSoapHttpPortClient {

@WebServiceRef
private static HCMDataLoader_Service hcmDataLoader_Service;
public HCMDataLoaderServiceSoapHttpPortClient() {
super();
}
public static void main(String[] args) {
hcmDataLoader_Service =
new HCMDataLoader_Service();
SecurityPolicyFeature[] securityFeatures =
new SecurityPolicyFeature[] { new
SecurityPolicyFeature("oracle/wss11_username_token_with_message_protection_client_polic
y") };
HCMDataLoader hcmLoaderService =
hcmDataLoader_Service.getHCMDataLoaderSoapHttpPort(securityFeatures);
BindingProvider wsbp = (BindingProvider)hcmLoaderService;
Map<String, Object> requestContext = wsbp.getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY,"Provide the applications
username");
requestContext.put(BindingProvider.PASSWORD_PROPERTY, "Provide the password");
requestContext.put("oracle.webservices.security.keystore.type", "JKS");
requestContext.put("oracle.webservices.security.keystore.location",
"Provide the location of the default-keystore.jks (including the file name)");
requestContext.put("oracle.webservices.security.keystore.password", "welcome");
requestContext.put("oracle.webservices.security.encryption.key.alias",
"orakey");
requestContext.put("oracle.webservices.security.encryption.key.password",
"welcome");
requestContext.put("oracle.webservices.security.recipient.key.alias",
"orakey");
String contentId = args[0];

14

Automating HCM Data Loader

String parameters = args[1];

String response;
try {
response =
hcmLoaderService.importAndLoadData(contentId,parameters);
System.out.println("The response received from the server is ...");
System.out.println(response);
} catch (ServiceException e) {
System.out.println("Error occurred during the invocation of the service ...");

e.printStackTrace();
}
}
}

To generate the class file you need the following JAR file:

ws.api_1.1.0.0.jar
This JAR file is available at the following location:

$MIDDLEWARE_HOME/modules
If you do not have the JAR file, it can be can be downloaded as part of JDeveloper. The JAR file is
available at the following location in the JDeveloper installation.

modules/ ws.api_1.1.0.0.jar
Compile the Java code.
javac -classpath <Provide the path of the folder where the JAX-WS files are
generated>;<Provide the location of the ws.api_1.1.0.0.jar>
HCMDataLoaderServiceSoapHttpPortClient.java

Run the class HCMDataLoaderServiceSoapHttpPortClient to invoke the HCM Data Loader

Integration Service.
java -classpath <Provide the path of the folder where the JAX-WS files are
generated>;<Provide the location of the weblogic.jar>;<Provide the location of the
jrf.jar>
com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLo
aderServiceSoapHttpPortClient <ContentId> <Parameters>

15

Integrating File-Based Loader with Oracle

Copyright 2013, Oracle and/or its affiliates. All rights reserved.

WebCenter Content
December 2013

This document is provided for information purposes only, and the contents hereof are subject to change without notice. This

Author: Pardhasaradhirao Veluguleti

document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in
law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any

Contributing Authors: Bill Kerr

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.

liability with respect to this document, and no contractual obligations are formed either directly or indirectly by this document. This
document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our
prior written permission.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and

Worldwide Inquiries:

are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are

Phone: +1.650.506.7000

trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. 0113

Fax: +1.650.506.7200
oracle.com