Use the HCM Data Loader Integration Web Service

You can use an HCM Data Loader SOAP web service to import and load the data files that are staged on the WebCenter Content server. You can process those data files manually from the Import and Load Data page in the Oracle Cloud HCM user interface.

You must first install Oracle JDeveloper 11.1.1.9, to get the libraries required to invoke SOAP web services from Oracle Cloud HCM.

About the HCM Data Loader Integration Service

You can use an Oracle Cloud HCM SOAP web service to upload files using the SOAP API.

You can obtain the Data Loader Service web service details from Oracle Fusion Cloud Human Resources in the Developer Connect link, under Tools in the Navigator menu, just like any other SOAP web service.

You can invoke the SOAP web service after you place the ZIP file that contains the DAT files on the WebCenter Content server. Then, you can secure it with the hcm/dataloader/import account. This web service can be used to import and load data in Oracle Cloud HCM.

About the SOAP Envelopes for Invoking the HCM Data Loader

When you invoke the HCM Data Loader SOAP web service, request and response envelops are sent and received.

You can use these envelopes to make a requests to the HCMDataLoader SOAP web service:

http://{Host}/hcmCommonDataLoader/HCMDataLoader

About the importAndLoadData method

The importAndLoadData method initiates the processing of a data file hosted on the WebCenter Content server. It is an asynchronous job that returns only the ProcessId of the submitted process.

Use this envelope to make a call to the importAndLoadData function in the SOAP web service.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:importAndLoadData xmlns:ns1="http://xmlns.oracle.com/apps/hcm/common/dataLoader/core/dataLoaderIntegrationService/types/">
            <ns1:ContentId></ns1:ContentId>
            <ns1:Parameters></ns1:Parameters>
        </ns1:importAndLoadData>
    </soap:Envelope>

The parameters for the importAndLoadData method that are sent with the envelope are:

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

Parameters: Name-value pairs. The following parameter names are available, but are not mandatory:

ImportMaximumErrors: Percentage of the file lines in an error that can occur for a business object before the import process stops.
LoadMaximumErrors: Percentage of business object instances in an 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. For example, Password Based Encryption (PBE).
DeleteSourceFile: Y or N value. If set to Y or left blank, deletes the source file from the WebCenter Content server after the file content is transferred into HCM Data Loader stage tables and is no longer required.

For example the <ns1:Parameters> tag can contain the following name and value pairs:<ns1:Parameters>ImportMaximumErrors=100,LoadMaximumErrors=100,LoadConcurrentThreads=4,FileEncryption=PGPSIGNED,DeleteSourceFile=N</ns1:Parameters>

The server responds with this envelope:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing"> 
	<env:Header> <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To> 
	  <wsa:Action>http://xmlns.oracle.com/apps/hcm/common/dataLoader/core/dataLoaderIntegrationService/HCMDataLoader/importAndLoadDataResponse</wsa:Action>
	   <wsa:MessageID>urn:uuid:ab36195f-775b-4688-a0e4-8a4e531e904c</wsa:MessageID>
	   <wsa:RelatesTo>urn:uuid:74c7b631-c20a-4d49-bf36-1f483f3dc43e</wsa:RelatesTo>
   </env:Header> 
	<env:Body> <ns0:importAndLoadDataResponse xmlns:ns0="http://xmlns.oracle.com/apps/hcm/common/dataLoader/core/dataLoaderIntegrationService/types/"> <result xmlns="http://xmlns.oracle.com/apps/hcm/common/dataLoader/core/dataLoaderIntegrationService/types/">7958</result> </ns0:importAndLoadDataResponse> 
	</env:Body> 
</env:Envelope>

About the getDataSetStatus method

The getDataSetStatus method returns the current status of the specified data file.

Use this envelope to make a call to the getDataSetStatus function in the SOAP web service.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:getDataSetStatus xmlns:ns1="http://xmlns.oracle.com/apps/hcm/common/dataLoader/core/dataLoaderIntegrationService/types/">
             <ns1:Parameters></ns1:Parameters>
        </ns1:getDataSetStatus>
    </soap:Envelope>

The parameters for the getDataSetStatus method that are sent with the envelope are:

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

ProcessId: The ID of the process initiated and returned by the importAndLoadData method.

Generate a Proxy Class for Invoking the HCM DataLoader

One option for invoking an Oracle Cloud HCM SOAP web service, is to use generated proxy classes.

You can generate proxy classes by providing the URL of the service WSDL file to your generator of choice. These proxy classes are used to invoke the web service.

Note:

Oracle Cloud HCM SOAP web services are protected by Oracle Web Services Manager (OWSM) security policies.

Sign in to Oracle Cloud HCM.
From the Navigator menu, locate the Tools heading, and then click Developer Connect.
In the Find search box, type Data Loader, and then click the search icon.
Click the Data Loader service. The Summary page of the service is displayed.
The Summary page shows information that is relevant to the SOAP web service, such as the WSDL file location.
Open a command prompt, and then run 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>
```
In the command, the first parameter is the folder where the generated files need to be placed. The second parameter is also the folder where the generated files need to be placed. The third parameter is the HCM Data Loader WSDL URL. For example:
```
wsimport -s "D:\HCMDataLoader" -d "D:\ HCMDataLoader" https://{host}/hcmCommonDataLoader/HCMDataLoader?wsdl
```
The generated files are placed in the following two folders:
- com
- sdo
Add the generated code to a JAR file:
```
zip loaderIntegrationProxy.jar -r * -
```

About the Security Implications When Using the HCM Data Loader

When a client calls an HCM Data Loader SOAP web service, the later must satisfy the message protection policy to ensure that the payload is transported in an encrypted way or over the SSL transport layer.

The HCMDataLoader web service is secured using the following Oracle Web Services Manager policy: oracle/wss11_saml_or_username_token_with_message_protection_service_policy.

On the client side, you can use the following Oracle Web Services Manager policy:oracle/wss11_username_token_with_message_protection_client_policy.

To use this policy, the message must be encrypted by using a public key that is provided by the server. When the message reaches the server, the message can be decrypted by the server's private key. You can create a KeyStore to import the certificate provided in the service WSDL file, however for security reasons you should prompt the user for the Oracle Cloud HCM password whenever you run your code.

You can create a properties text file that can be parsed within your code to access the Keystore information, for example:

FUSION_USERNAME=<Your Oracle Global Human Resources Cloud User Name>
DATAPATH=C:\\My\\Assets\\cloud.asset.hcm.java-dataload-example\\data\\
HCM_DATA_LOADER_SERVICE_WSDL_LOCATION=https://<<FusionURL>/hcmCommonDataLoader/HCMDataLoader?wsdl
UCM_IDC_WEBSERVICE_LOCATION=https://<FusionURL>/idcws/GenericSoapPort
KEYSTORE_LOCATION=<Your Keystore trust location>
KEYSTORE_PASSWORD=<YourTrustPassword>
KEYSTORE_ALIAS=orakey
GETDATASETSTATUS_DELAY=5
OK=OK
ERROR=Error
WARNING=Warning
CSV_FILE_ENCODING=UTF-8
DATA_SEPERATOR=;

Prompt the user for their Oracle Cloud HCM credentials using the following:

// Accept password from user
Scanner scanReader = new Scanner(System.in);  // Reading from System.in
System.out.println("Enter password for user "+propertiesFile.getProperty("FUSION_USERNAME")+" :");
fusionUserPass= scanReader.next(); // Scans the next token of the input as an int.
scanReader.close();

In the example, fusionUserPass is a variable that can be used to store the user's Oracle Cloud HCM password, and then passed to the HCM Data Loader SOAP web service.

Invoke the HCM DataLoader SOAP Web Service

You can load data from a ZIP file to Oracle Cloud HCM by using the HCM Data Loader SOAP web service from a Java class.

First create a ZIP file and upload it to the WebCenter Content server either manually or programmatically. Then you can load the data using the importAndLoadData web service.

Note:

The code samples provided in this solution were tested with JDK version 8 for invoking web services on Oracle WebLogic Server 12c. For use with other JDK and Oracle WebLogic Server versions, test the code with libraries specific to the desired versions.

Create a client class in the folder: /com/oracle/xmlns/apps/hcm/common/dataloader/core/dataloaderintegrationservice/.
To generate the class you need to have the following JAR file:
- For WebLogic Server 11g: ws.api_1.1.0.0.jar
- For WebLogic Server 12c: wls-api.jar
This JAR file is available at the following location in the JDeveloper installation folder:
- For WebLogic Server 11g: $MIDDLEWARE_HOME/modules
- For WebLogic Server 12c: $MIDDLEWARE_HOME/wlserver/server/lib

Make sure to import the following Java libraries in your Java Code:

import com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLoader;
import com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLoader_Service;
import com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.ServiceException;
import javax.xml.ws.BindingProvider;
import weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature;

Create a function that returns an HCMDataLoader object, and receives url, username, password, and keystore as parameters. For example:

public static HCMDataLoader getHCMDataLoaderService(String url, String username, String password, String keystore)
			throws MalformedURLException {
		//The code in the next steps is placed within the function body
}

Inside the function body, create the SOAP web service object.

HCMDataLoader_Service webService = new HCMDataLoader_Service(new URL("/hcmCommonDataLoader/HCMDataLoader?wsdl));

SecurityPolicyFeature[] securityFeatures = new SecurityPolicyFeature[] { 
				new SecurityPolicyFeature("oracle/wss_username_token_over_ssl_client_policy") 
}; 

HCMDataLoader hcmDataLoader = webService.getHCMDataLoaderSoapHttpPort(securityFeatures);

Create a BindingProvider object and set its context parameters.

BindingProvider wsbp = (BindingProvider) hcmDataLoader;
Map<String, Object> requestContext = wsbp.getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY, username);
requestContext.put(BindingProvider.PASSWORD_PROPERTY, password);
return hcmDataLoader;

Load the data into Oracle Cloud HCM by using the importAndLoadData function.

HCMDataLoader hcmDataLoaderService = HCMDataLoaderUtil.getHCMDataLoaderService(url, username, password,
		keystore);

String parameters = ""; // args[1];

try {
	String response = hcmDataLoaderService.importAndLoadData(contentId, parameters);

	return response;
} catch (ServiceException e) {
	logger.severe("Error occurred during importAndLoad call  ..." + e.getLocalizedMessage());
	throw e;
}

You can create another function to get the status from the data file that you uploaded:

public static String invokeGetDataSetStatus(String url, String username, String password, String keystore,
			Long processId, String getDataSetStatusDelay)
			throws ServiceException, ParserConfigurationException, SAXException, IOException, InterruptedException {
				//The code in the next steps is placed within this function body
}

Retrieve the status response by using the getDataSetStatus function:

HCMDataLoader hcmLoaderService = getHCMDataLoaderService(url, username, password, keystore);
String response = hcmLoaderService.getDataSetStatus("ProcessId=" + processId);
String loadStatus = getLoadStatusFromResponse(response); // To save the status from the response to a String variable

The getDataSetStatus returns an XML object that contains details about the load and import process.

Create another function to parse the XML response from the getDataSetStatus call.

public static String getLoadStatusFromResponse(String xmlResult)
			throws ParserConfigurationException, SAXException, IOException {
		DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
		DocumentBuilder builder = factory.newDocumentBuilder();
		Document document = builder.parse(new InputSource(new StringReader(xmlResult)));
		NodeList flowList = document.getElementsByTagName("DATA_SET_STATUS");
		NodeList childList;
		for (int i = 0; i < flowList.getLength(); i++) {
			childList = flowList.item(i).getChildNodes();
			for (int j = 0; j < childList.getLength(); j++) {
				Node childNode = childList.item(j);
				if ("DATA_SET".equals(childNode.getNodeName())) {
					NodeList dataSeteChildNodes = childNode.getChildNodes();
					{
						for (int k = 0; k < dataSeteChildNodes.getLength(); k++) {
							{
								Node childDSNode = dataSeteChildNodes.item(k);
								if ("STATUS".equals(childDSNode.getNodeName())) {
									String status = dataSeteChildNodes.item(k).getTextContent().trim();
									System.out.println("Current Status of the Data Set "
											+ dataSeteChildNodes.item(k).getTextContent().trim());
									return status;
								}
							}
						}
					}
				}
			}
		}
		return "ERROR";
	}

Once your Java code is complete, compile it using the javac command:

For WebLogic Server 11g:

javac -classpath path of the folder where with generated JAX-WS files;location of ws.api_1.1.0.0.jar HCMDataLoaderServiceSoapHttpPortClient.java

For WebLogic Server 12c:

javac -classpath path of the folder where with generated JAX-WS files;location of wls-api.jar HCMDataLoaderServiceSoapHttpPortClient.java

Run the HCMDataLoaderServiceSoapHttpPortClient class to invoke the HCM Data Loader Integration Service, using the java command:

For WebLogic Server 11g:

java -classpath path of the folder where with generated JAX-WS files;location of weblogic.jar;location of jrf.jar com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLoaderServiceSoapHttpPortClient ContentId Parameters

For WebLogic Server 12c:

java -classpath path of the folder where with generated JAX-WS files;location of wlthint3client.jar;location of wls-api.jar com.oracle.xmlns.apps.hcm.common.dataloader.core.dataloaderintegrationservice.HCMDataLoaderServiceSoapHttpPortClient ContentId Parameters