HCMデータ・ローダー統合Webサービスの使用

HCMデータ・ローダーSOAP Webサービスを使用して、WebCenterコンテンツ・サーバーにステージングされたデータ・ファイルをインポートおよびロードできます。これらのデータファイルは、Oracle Cloud HCMユーザー・インタフェースの「データのインポートおよびロード」ページから手動で処理できます。

SOAP WebサービスをOracle Cloud HCMから起動するために必要なライブラリを取得するには、最初にOracle JDeveloper 11.1.1.9をインストールする必要があります。

HCMデータ・ローダー統合サービスについて

Oracle Cloud HCM SOAP Webサービスを使用して、SOAP APIを使用してファイルをアップロードできます。

データ・ローダー・サービスWebサービスの詳細は、他のSOAP Webサービスと同様に、「ナビゲータ」メニューの「ツール」の下にある「開発者接続」リンクのOracle Fusion Cloud Human Resourcesから取得できます。

DATファイルを含むZIPファイルをWebCenter Contentサーバーに配置した後で、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サービスを呼び出すオプションの1つは、生成されたプロキシ・クラスを使用することです。

選択したジェネレータにサービスWSDLファイルのURLを指定することで、プロキシ・クラスを生成できます。これらのプロキシ・クラスは、Webサービスの起動に使用されます。

ノート:

Oracle Cloud HCM SOAP Webサービスは、Oracle Web Services Manager (OWSM)セキュリティ・ポリシーによって保護されます。

Oracle Cloud HCMにサインインします。
「ナビゲータ」メニューから、「ツール」見出しを見つけて、「Developer Connect」をクリックします。
「検索」検索ボックスで、「データ・ローダー」と入力し、検索アイコンをクリックします。
「データ・ローダー」サービスをクリックします。サービスの「サマリー」ページが表示されます。
サマリー・ページには、WSDLファイルの場所など、SOAP Webサービスに関連する情報が表示されます。
コマンド・プロンプトを開き、$JAVA_HOME/binにあるwsimportコマンドを実行します:
```
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>
```
コマンドの最初のパラメータは、生成されたファイルを配置する必要があるフォルダです。2番目のパラメータは、生成されたファイルを配置する必要があるフォルダでもあります。3番目のパラメータは、HCMデータ・ローダーWSDL URLです。例:
```
wsimport -s "D:\HCMDataLoader" -d "D:\ HCMDataLoader" https://{host}/hcmCommonDataLoader/HCMDataLoader?wsdl
```
生成されたファイルは、次の2つのフォルダに配置されます。
- com
- sdo
生成されたコードをJARファイルに追加します。
```
zip loaderIntegrationProxy.jar -r * -
```

HCMデータ・ローダーを使用する際のセキュリティ上の意味について

クライアントがHCMデータ・ローダー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データ・ローダーSOAP Webサービスに渡すために使用できる変数です。

HCM DataLoader SOAP Webサービスの起動

JavaクラスからHCMデータ・ローダーSOAP Webサービスを使用して、ZIPファイルからOracle Cloud HCMにデータをロードできます。

最初にZIPファイルを作成し、手動またはプログラムでWebCenter Contentサーバーにアップロードします。その後、importAndLoadData Webサービスを使用してデータをロードできます。

ノート:

このソリューションで提供されるコード・サンプルは、Oracle WebLogic Server 12cでWebサービスを呼び出すためのJDKバージョン8でテストされました。他のJDKおよびOracle WebLogic Serverバージョンで使用するには、必要なバージョンに固有のライブラリを使用してコードをテストします。

/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

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;

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
}

関数本体内で、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);

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;

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

アップロードしたデータ・ファイルからステータスを取得する別の関数を作成できます。

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
}

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オブジェクトを返します。

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

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

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