21 fbl integration-01

An Oracle White Paper

October 2013

Oracle Fusion Human Capital Management 11g Release 7 (11.1.7)

Integrating File-Based Loader with Oracle WebCenter Content


Introduction ....................................................................................... 1

Audience ....................................................................................... 1

Oracle WebCenter Content and File-Based Loader ........................... 2

Methods of Staging Files with Oracle WebCenter Content ................ 2

File Import and Export Interface ..................................................... 2

WebCenter Content Document Transfer Utility Interface ............... 4

Remote Intradoc Client (RIDC) ...................................................... 5

Loader Integration Service ................................................................. 9

Sample Code to Invoke LoaderIntegrationService ......................... 9


1

Introduction

This document shows how to integrate Oracle Fusion Human Capital Management (HCM) 11g

Release 7 (11.1.7) File-Based Loader (FBL) with Oracle WebCenter Content.

WebCenter Content is the staging mechanism for files to be loaded and processed by FBL.

Two topics are covered:

The available methods for staging a zip file on the WebCenter Content server for

consumption by FBL

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

See the File-Based Loader User’s Guide (document ID 1533860.1) for general information

about FBL and instructions for constructing the zip file containing data to be loaded.

Audience

This document is mainly technical in nature and will therefore be of interest to integration

architects and developers needing to understand how to interact programmatically with FBL.

An understanding of WS-Security is desirable. Java is used for supporting example code but

is not a requirement for integration.

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=16300137183930&id=1533860.1&_afrWindowMode=0&_adf.ctrl-state=5b4fktdhb_4


2

Oracle WebCenter Content and File-Based Loader

WebCenter Content is the replacement infrastructure for the staging of data files for processing by

FBL. It supersedes the SFTP option provided with Oracle Fusion HCM prior to Release 7.

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 FBL on the WebCenter Content server. Once a

file is staged it can be processed by invoking an externally available web service,

LoaderIntegrationService, 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.

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)

File Import and Export Interface

You can stage an FBL zip file 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 FBL.

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


3

Figure 2. Uploading a File Using the File Import and Export Interface

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

One of the parameters required for both the LoaderIntegrationService 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 Load HCM Data for Coexistence page.

Note that this function is delivered in Oracle Fusion HCM Release 7 Patch Bundle 3.

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 Load HCM Data for Coexistence.

3. On the Load HCM Data for Coexistence page, click Import.

4. In the Import and Load HCM Data dialog box, enter the content ID that you obtained when

loading the data file using the File Import and Export interface.

5. Select an individual business object or All to load all business objects in the zip file.

6. Provide a meaningful batch name. Object names are prefixed with the batch name to provide a unique

batch name for each batch.

7. Set the Loader Run Type parameter to Import (to import data for later loading) or Import and

Load Batch Data (to both import the data and initiate the data load).


4

8. Click Submit.

Figure 3. Manually Loading and Optionally Processing an FBL Zip File Using the Load HCM Data for

Coexistence Interface

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

http://www.oracle.com/technetwork/middleware/webcenter/content/downloads/index.html


5

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

The dDocName value (which is equivalent to the content ID) returned when executing the above

statement is required for the LoaderIntegrationService call described later in this document.

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 Developer's 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.


6

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 java.io.File;

import java.io.FileInputStream;

import java.io.InputStream;

import java.io.IOException;

import oracle.stellent.ridc.IdcClient;

import oracle.stellent.ridc.IdcClientException;

import oracle.stellent.ridc.IdcClientManager;

import oracle.stellent.ridc.IdcContext;

import oracle.stellent.ridc.model.DataBinder;

import oracle.stellent.ridc.model.TransferFile;

import 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


7

relevant URL

IdcContext userContext = new IdcContext("HCM_ADMIN", "Password"); // replace with

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");


8

request.addFile("primaryFile", primaryFile);

request.putLocal("dDocTitle", dDocTitle);

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 FBL

IdcService The service to invoke. CHECKIN_UNIVERSAL for uploading files

dDocName The content ID for the content item. Value passed to LoaderIntegrationService

dDocAuthor The content item author (contributor).

dDocTitle The content item title.

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

are enabled.

hcm$/dataloader$/import$

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


9

Loader Integration Service

File-Based Loader (FBL) in Release 7 implements a web service that can be used to initiate the load

and subsequent processing of data files on the WebCenter Content server. As noted earlier, you can

process such data files manually from the Load HCM Data for Coexistence page.

Once you have placed the zip file containing the .dat files in the WebCenter Content folder

hcm/dataloader/import, the web service LoaderIntegrationService can be invoked to perform an

Import or Import and Load of data to Fusion.

Service invocation details for the LoaderIntegrationService 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 LoaderIntegrationService

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 LoaderIntegrationService.

http://{Host}/hcmCommonBatchLoader/LoaderIntegrationService

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns1:submitBatch

xmlns:ns1="http://xmlns.oracle.com/apps/hcm/common/batchLoader/core/loaderIntegrationSe

rvice/types/">

<ns1:ZipFileName></ns1:ZipFileName>

<ns1:BusinessObjectList></ns1:BusinessObjectList>

<ns1:BatchName></ns1:BatchName>

<ns1:LoadType></ns1:LoadType>

<ns1:AutoLoad></ns1:AutoLoad>

</ns1:submitBatch>

</soap:Body>

</soap:Envelope>

Figure 8. Sample Service Interface for the LoaderIntegrationService

http://fusionappsoer.oracle.com/


10

Parameter Description

ZipFileName Content ID of the file on the WebCenter Content server (the same value as dDocName in the WebCenter

Content Java call)

BusinessObjectList Name of the business object to be loaded. Repeat this tag for each business object to be loaded.

BatchName Name of the batch when it is created in Oracle Fusion.

LoadType The type of load. Can be either FBL or HR2HR. Use FBL.

AutoLoad Indicate whether to load the data into Oracle Fusion.

N = Import only

Y = Import and Load

Note: This parameter in the service replaces the setup parameter Load HCM Data Files Automatically on the

Manage HCM Configuration for Coexistence page.

Figure 9. Parameters of the LoaderIntegrationService

Implications of Security Policy on the LoaderIntegrationService

In Release 7, the LoaderIntegrationService 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.

Note: Previously this service could be called directly from the browser, supplying the parameters as

requested by the Oracle WSM Web Services Test Page. However, this test page is used to test policies

that implement username tokens to authenticate users without message protection. The above policy

used to secure the LoaderIntegrationService precludes the use of the Web Services Test Page for this

reason.

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

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

Parameter Description

WSBindingProvider.USERNAME_PROPERTY 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 LoaderIntegrationService 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 Loader

Integration Service URL>

e.g, wsimport -s "D:\LoaderIntegrationService" -d "D:\LoaderIntegrationService"

https://{host}/hcmCommonBatchLoader/LoaderIntegrationService?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 LoaderIntegrationServiceSoapHttpPortClient for invoking the

LoaderIntegrationService. The class must be created in the folder

com/oracle/xmlns/apps/hcm/common/batchloader/core/loaderintegrationservice:

package com.oracle.xmlns.apps.hcm.common.batchloader.core.loaderintegrationservice;


13

import java.util.ArrayList;

import java.util.Map;

import java.util.StringTokenizer;

import javax.xml.ws.BindingProvider;

import javax.xml.ws.WebServiceRef;

import weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature;

public class LoaderIntegrationServiceSoapHttpPortClient {

@WebServiceRef

private static LoaderIntegrationService_Service loaderIntegrationService_Service;

public static void main(String[] args) {

loaderIntegrationService_Service =

new LoaderIntegrationService_Service();

SecurityPolicyFeature[] securityFeatures =

new SecurityPolicyFeature[] { new

SecurityPolicyFeature("oracle/wss11_username_token_with_message_protection_client_polic

y") };

LoaderIntegrationService loaderIntegrationService =

loaderIntegrationService_Service.getLoaderIntegrationServiceSoapHttpPort(securityFeatur

es);

BindingProvider wsbp = (BindingProvider)loaderIntegrationService;

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 fileName = args[0];

String batchName = args[1];

String autoLoad = args[2];

String businessObj = args[3];

StringTokenizer strTok = new StringTokenizer(businessObj, ",");

ArrayList businessObjList = new ArrayList();

while (strTok.hasMoreTokens()) {

businessObjList.add(strTok.nextToken());

}

String response;

try {

response =

loaderIntegrationService.submitBatch(fileName, businessObjList,

batchName, "FBL",

autoLoad);

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:


14

$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>

LoaderIntegrationServiceSoapHttpPortClient.java

Run the class LoaderIntegrationServiceSoapHttpPortClient to invoke the 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.batchloader.core.loaderintegrationservice.LoaderIntegr

ationServiceSoapHttpPortClient <ZipFileName> <BatchName> <AutoLoad>

<BusinessObjectList>

http://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.html

Integrating File-Based Loader with Oracle

WebCenter Content

October 2013

Author: Pardhasaradhirao Veluguleti

Contributing Authors: Bill Kerr

Oracle Corporation

World Headquarters

500 Oracle Parkway

Redwood Shores, CA 94065

U.S.A.

Worldwide Inquiries:

Phone: +1.650.506.7000

Fax: +1.650.506.7200

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

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

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

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

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 Devices. UNIX is a registered trademark of The Open Group. 0113