1. 將資料載入 Oracle Fusion Cloud Human Capital Management (HCM)
  2. 使用 HCM 資料載入器整合 Web 服務

使用 HCM 資料載入器整合 Web 服務

您可以使用 HCM 資料載入器 SOAP Web 服務來匯入與載入 WebCenter Content 伺服器上暫存的資料檔。您可以從 Oracle Cloud HCM 使用者介面的匯入與載入資料頁面，手動處理這些資料檔。

您必須先安裝 Oracle JDeveloper 11.1.1.9，才能取得從 Oracle Cloud HCM 呼叫 SOAP Web 服務所需的程式庫。

關於 HCM 資料載入器整合服務

您可以使用 Oracle Cloud HCM SOAP Web 服務，透過 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.

在 WebCenter Content 伺服器上放置包含 DAT 檔案的 ZIP 檔案之後，您可以呼叫 SOAP Web 服務。之後，您可以使用 hcm/dataloader/import 帳戶來保護帳戶。此 Web 服務可用來在 Oracle Cloud HCM 中匯入與載入資料。

關於呼叫 HCM 資料載入器的 SOAP 信封

當您呼叫「HCM 資料載入器 SOAP」Web 服務時，會傳送並接收要求和回應附加訊息。
您可以使用這些附加訊息對 HCMDataLoader SOAP Web 服務提出要求： 
http://{Host}/hcmCommonDataLoader/HCMDataLoader

關於 importAndLoadData 方法

importAndLoadData 方法會起始處理 WebCenter Content 伺服器上代管的資料檔。這是僅傳回已提交處理之 ProcessId 的非同步工作。

您可以使用此附加訊息呼叫 SOAP Web 服務中的 importAndLoadData 函數。 

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

與附加訊息一起傳送之 importAndLoadData 方法的參數如下：

ContentId ：WebCenter Content 伺服器上檔案的內容 ID (與 WebCenter Content Java 呼叫中的 dDocName 參數值相同)。

參數：名稱 - 值組。以下是可用的參數名稱，但並非必要：

  • ImportMaximumErrors：匯入處理停止前，業務物件所能發生的錯誤檔案行數百分比。

  • LoadMaximumErrors：驗證與載入處理停止前，業務物件中所能發生的錯誤業務物件實例百分比。

  • LoadConcurrentThreads：驗證或載入時的並行執行緒數目。

  • LoadGroupSize：由並行執行緒作為單一工作單元處理的業務物件數。

  • FileEncryption：檔案加密類型。例如，密碼型加密 (PBE)。

  • DeleteSourceFile：Y 或 N 值。如果設為 Y 或保留空白，則在檔案內容轉移至「HCM 資料載入器」暫存表後，從 WebCenter Content 伺服器刪除來源檔案，不再需要。

例如，<ns1:Parameters> 標記可包含下列名稱和值組：<ns1:Parameters>ImportMaximumErrors=100,LoadMaximumErrors=100,LoadConcurrentThreads=4,FileEncryption=PGPSIGNED,DeleteSourceFile=N</ns1:Parameters>

伺服器以此信封回應：
<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>

關於 getDataSetStatus 方法

getDataSetStatus 方法會傳回指定資料檔案的目前狀態。

您可以使用此附加訊息呼叫 SOAP Web 服務中的 getDataSetStatus 函數。 

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

與附加訊息一起傳送之 getDataSetStatus 方法的參數如下：

ContentId ：WebCenter Content 伺服器上檔案的內容 ID (與 WebCenter Content Java 呼叫中的 dDocName 參數值相同)。

ProcessId ：由 importAndLoadData 方法起始和傳回的程序 ID。

產生用以呼叫 HCM DataLoader 的代理主機類別

呼叫 Oracle Cloud HCM SOAP Web 服務的一個選項是使用產生的代理主機類別。

您可以將服務 WSDL 檔案的 URL 提供給所選擇的產生器，以產生代理類別。這些代理類別用於呼叫 Web 服務。

注意：

Oracle Cloud HCM SOAP Web 服務受到 Oracle Web Services Manager (OWSM) 安全原則的保護。
  1. 登入 Oracle Cloud HCM 。
  2. 從導覽器功能表中，找出工具標題，然後按一下開發人員連線。
  3. 在尋找搜尋方塊中，輸入資料載入器，然後按一下搜尋圖示。
  4. 按一下資料載入程式服務。服務的「摘要」頁面便會顯示。
    「摘要」頁面會顯示與 SOAP Web 服務相關的資訊，例如 WSDL 檔案位置。
  5. 開啟命令提示字元，然後執行 wsimport 指令，該指令可在 $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>

    在命令中，第一個參數是放置產生之檔案的資料夾。第二個參數也是必須放置產生之檔案的資料夾。第三個參數是「HCM 資料載入器 WSDL URL」。例如：

    wsimport -s "D:\HCMDataLoader" -d "D:\ HCMDataLoader" https://{host}/hcmCommonDataLoader/HCMDataLoader?wsdl

    產生的檔案會放置在下列兩個資料夾中：

    • com

    • sdo

  6. 將產生的程式碼新增至 JAR 檔案：
    zip loaderIntegrationProxy.jar -r * -

關於使用 HCM 資料載入器時的安全影響

當從屬端呼叫 HCM Data Loader SOAP Web 服務時，稍後必須滿足訊息保護原則，以確保有效負載以加密方式或透過 SSL 傳輸層傳輸。

HCMDataLoader Web 服務使用下列 Oracle Web Services Manager 原則保護：oracle/wss11_saml_or_username_token_with_message_protection_service_policy。

在從屬端，您可以使用下列 Oracle Web Services Manager 原則：oracle/wss11_username_token_with_message_protection_client_policy。

若要使用此原則，訊息必須使用伺服器提供的公開金鑰加密。當訊息到達伺服器時，可以用伺服器的私密金鑰將訊息解密。您可以建立 KeyStore 來匯入服務 WSDL 檔案中提供的憑證，但基於安全上的理由，您每次執行程式碼時，都應該提示使用者輸入 Oracle Cloud HCM 密碼。

您可以建立可在程式碼中剖析的特性文字檔，以存取 Keystore 資訊，例如： 

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=;

使用下列項目提示使用者輸入其 Oracle Cloud HCM 證明資料： 

// 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();

在範例中，fusionUserPass 是一個變數，可用來儲存使用者的 Oracle Cloud HCM 密碼，然後傳送至 HCM Data Loader SOAP Web 服務。

呼叫 HCM DataLoader SOAP Web 服務

您可以使用 Java 類別的 HCM Data Loader SOAP Web 服務，將資料從 ZIP 檔案載入 Oracle Cloud HCM 。

請先建立 ZIP 檔案，並將其以手動或程式設計方式上傳至 WebCenter Content 伺服器。然後，您可以使用 importAndLoadData Web 服務來載入資料。

注意：

本解決方案提供的程式碼範例已使用 JDK 版本 8 在 Oracle WebLogic Server 12c 上呼叫 Web 服務進行測試。若要與其他 JDK 和 Oracle WebLogic Server 版本搭配使用，請以所需版本特有的程式庫來測試程式碼。

  1. 在資料夾中建立從屬端類別：/com/oracle/xmlns/apps/hcm/common/dataloader/core/dataloaderintegrationservice/。
    若要產生類別，您需要有下列 JAR 檔案：
    • 若為 WebLogic 伺服器 11g：ws.api_1.1.0.0.jar
    • 若為 WebLogic 伺服器 12c：wls-api.jar

    此 JAR 檔案位於 JDeveloper 安裝資料夾的下列位置：

    • 若為 WebLogic 伺服器 11g：$MIDDLEWARE_HOME/modules
    • 若為 WebLogic 伺服器 12c：$MIDDLEWARE_HOME/wlserver/server/lib
  2. 確定在您的 Java 程式碼中匯入下列 Java 程式庫：
    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;
  3. 建立傳回 HCMDataLoader 物件的函數，並接收 url、username、password 和 keystore 作為參數。分隔符號分隔)，例如：
    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
}
  4. 在函數主體內，建立 SOAP Web 服務物件。
    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);
  5. 建立 BindingProvider 物件並設定其相關資訊環境參數。
    BindingProvider wsbp = (BindingProvider) hcmDataLoader;
Map<String, Object> requestContext = wsbp.getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY, username);
requestContext.put(BindingProvider.PASSWORD_PROPERTY, password);
return hcmDataLoader;
  6. 使用 importAndLoadData 函數將資料載入 Oracle Cloud HCM 。
    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;
}
  7. 您可以建立另一個函數，從您上傳的資料檔取得狀態：
    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
}
  8. 使用 getDataSetStatus 函數擷取狀態回應：
    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

    getDataSetStatus 會傳回包含載入和匯入程序相關詳細資訊的 XML 物件。

  9. 建立另一個函數來剖析 getDataSetStatus 呼叫的 XML 回應。
    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";
	}
  10. Java 程式碼完成後，請使用 javac 指令來編譯它：
    • 若為 WebLogic 伺服器 11g： 
      javac -classpath path of the folder where with generated JAX-WS files;location of ws.api_1.1.0.0.jar HCMDataLoaderServiceSoapHttpPortClient.java
    • WebLogic 伺服器 12c： 
      javac -classpath path of the folder where with generated JAX-WS files;location of wls-api.jar HCMDataLoaderServiceSoapHttpPortClient.java
  11. 使用 java 命令執行 HCMDataLoaderServiceSoapHttpPortClient 類別以呼叫 HCM 資料載入器整合服務：
    • 若為 WebLogic 伺服器 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
    • WebLogic 伺服器 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