チュートリアル：CData Paylocity BizTalk Adapter を使ったアップデートグラムの実行

こんにちは！ウェブ担当の加藤です。マーケ関連のデータ分析や整備もやっています。

CData BizTalk Adapter for Paylocity は、BizTalk のPaylocity でSQL コマンド、アップデートグラム、ストアドプロシージャを実行することを可能にします。ここでは、アップデートグラムを使用して、Paylocity を挿入するアプリケーションのウォークスルーについて説明します。

1. 一方向のファイル受信場所はアップデートグラムを含むXML ドキュメントをピックアップします。
2. ドキュメントは、アダプタ用に構成された要請応答送信ポートにルーティングされます。
3. アダプタはコマンドを実行します。挿入の結果には、新しいレコードのId と、影響を受ける行が含まれています。
4. Paylocity からの応答は、一方向のファイル送信ポートにルーティングされ、BizTalk メッセージをファイルに書き込みます。

サンプルアプリケーションを作成する

以下のセクションでは、サンプルアプリケーションの作成について説明します。

1. スキーマとアップデートグラムインスタンスを生成する
2. 受信ポートを構成する
3. ファイルの受信場所を構成する
4. 要請応答送信ポートにアダプタを構成する
5. ファイルの送信ポートを構成する
6. アプリケーションを介してBizTalk メッセージをルーティングするフィルタを作成する
7. ロケーションとポートを登録し、有効にする
8. アプリケーションログを表示する

スキーマとアップデートグラムインスタンスを生成する

Visual Studio のウィザードを使用することで、スキーマとアップデートグラムインスタンスを生成することができます。

1. プロジェクトにアダプタを追加する
2. 挿入スキーマを生成する
3. アップデートグラムインスタンスを生成する

プロジェクトにアダプタを追加する

［Add Adapter］ウィザードを使用して、プロジェクトにアダプタを追加します。アダプタを使用して、挿入したいテーブルに関する［Employee］などのPaylocity メタデータをクエリします。

1. ［Solution Explorer］の［project］で右クリックし、［Add］->［Add Generated Items］と進みます。
2. ［resulting dialog box］の［Add Adapter Metadata］を選択します。
3. 表示される［Add Adapter］ウィザードで、リストからCData BizTalk Adapter for Paylocity を選択します。
4. ［Port menu］では、選択を空白のままにします。構成済みアダプタの接続文字列を使用したい場合には、BizTalkアプリケーションから送信ポート、または受信場所を選択します。

挿入スキーマを生成する

Paylocity のデータを挿入するアップデートグラムを作成するためのテンプレートとしてスキーマを使用します。スキーマは、XMLリクエストと応答を定義する.xsd ファイルです。例として、挿入アップデートグラムを生成する方法を説明します。以下の手順に従って、update とdelete のアップデートグラムを生成できます。

1. ［Schema］ウィザードの［Connection String］ページで、認証資格情報とその他の接続プロパティを入力します。
2. 次のステップでは、［Send Port］オプションを選択します。
3. ［One-Way］オプションをオフにします。［One-Way］オプションは、返されたAffectedRows値など、アップデートグラムのアダプタからのすべての応答を無視します。新しく作成されたId の行も返されます。［One-Way］オプションを無効にすることで、Id の取得をサポートするアップデートグラムスキーマを取得できます。
4. ［Command Type］ メニューで、アップデートグラムを選択します。

5. ［Insert］オプションを選択し、挿入したいテーブルとカラムを選択します。このチュートリアルは、FirstName とLastName を使用しています。

   Noteアップデートグラムを作成する際、挿入はスキーマに含ませたカラムに限定されます。

6. 概要ページで、定義した設定を確認し、［Finish］をクリックしてウィザードを閉じます。

アップデートグラムを生成する

このステップでは、後のステップでアダプタに送られるXML メッセージを作成します。［Solution Explorer］にある.xsd ファイルを右クリックし、［Generate Instance］をクリックしてアップデートグラムを作成します。アップデートグラムが保存される場所は、［Output］タブに表示されます。

アップデートグラムは、Paylocity から求められる応答を定義するよう構成されています。アップデートグラムの例や詳細については、アダプタのヘルプドキュメントをご覧ください。

受信ポートを構成する

アプリケーションに受信場所を追加するには、まず受信ポートを追加する必要があります。受信ポートは複数の受信場所からのデータを受け取ることができます。

1. ［BizTalk Server Administration Console］でアプリケーションを開きます。
2. ［Receive Ports］を右クリックし、［New］->［One-Way Receive Port］と進みます。受信ポートプロパティのダイアログが表示されます。
3. 受信ポートの名前を入力します。

ファイル受信場所を構成する

静的な一方向のファイル受信場所は、アップデートグラムを含むBizTalk メッセージを作成します。

1. ［Receive Locations］を右クリックし、［New］->［One-Way Receive Location］と進みます。
2. 新しい受信場所がメンバとなる受信ポートを選択します。［Receive Location Properties］ダイアログが表示されます。
3. 受信場所の名前を入力します。
4. ［Transport Type］メニューで、［FILE］を選択します。
5. ［Configure］をクリックします。［File Transport Properties］ダイアログが表示されます。
6. ［Receive Folder］ボックスに、［DemoOutbound］のようなフォルダへのパスを入力します。受信場所はこのフォルダをスキャンし、［File mask］ボックスの条件に一致するファイルを探します。
7. ［Receive Location Properties］ダイアログの［Receive Pipeline］メニューで、デフォルトオプションの［PassThruReceive］を選択します。

要請応答送信ポートで、Paylocity アダプタを構成する

コンフィギュレーションは、以下のステップで構成されています。

1. 要請応答送信ポートを作成、構成する
2. アダプタを構成する
3. Paylocity への接続を構成する

要請応答送信ポートを作成、構成する

要請応答送信ポートを使用して、 アップデートグラムコマンドの結果を取得します。このチュートリアルでは、新しく挿入されたレコードのId がBizTalkで返されます。

1. ［BizTalk Administration Console］でアプリケーションを開きます。
2. ［Send Ports］を右クリックし、［New］->［Static Solicit-Response Send Port］を選択すると、送信ポートプロパティのダイアログが表示されます。
3. 送信ポートの名前を入力します。
4. ［Transport Type］メニューで、CData.Paylocity を選択します。

CData Paylocity アダプタを構成する

［Adapter Transport Properties］ダイアログで、アダプタが実行するコマンドを定義します。

1. 送信ポートのプロパティで、［Configure］ボタンをクリックします。［Adapter Transport Properties］ダイアログが表示されます。
2. ［CommandType］プロパティで、アップデートグラムを選択します。

プロパティとその機能についての説明は、ヘルプドキュメントの［Adapter Configuration］を参照してください。

Paylocity への接続を構成する

Paylocity への接続に必要な資格情報とその他のプロパティを設定します。

1. ［Adapter Transport］プロパティダイアログで、［Connection String］プロパティのボタンをクリックします。［Connection String Options］ダイアログが表示されます。

2. 接続プロパティを入力してください。

   下は一般的な接続文字列です。

   OAuthClientID=YourClientId;OAuthClientSecret=YourClientSecret;RSAPublicKey=YourRSAPubKey;Key=YourKey;IV=YourIV;InitiateOAuth=GETANDREFRESH

   Paylocity への接続を確立するには以下を設定します。

   • RSAPublicKey：Paylocity アカウントでRSA 暗号化が有効になっている場合は、Paylocity に関連付けられたRSA キーを設定。

     このプロパティは、Insert およびUpdate ステートメントを実行するために必須です。この機能が無効になっている場合は必須ではありません。

   • UseSandbox：サンドボックスアカウントを使用する場合はTrue に設定。
   • CustomFieldsCategory：Customfields カテゴリに設定。これは、IncludeCustomFields がtrue に設定されている場合は必須です。デフォルト値はPayrollAndHR です。
   • Key：Paylocity の公開鍵で暗号化されたAES 共通鍵（base 64 エンコード）。これはコンテンツを暗号化するためのキーです。

     Paylocity は、RSA 復号化を使用してAES 鍵を復号化します。
     これはオプションのプロパティで、IV の値が指定されていない場合、ドライバーは内部でキーを生成します。

   • IV：コンテンツを暗号化するときに使用するAES IV（base 64 エンコード）。これはオプションのプロパティで、Key の値が指定されていない場合、ドライバーは内部でIV を生成します。

   OAuth

   OAuth を使用してPaylocity で認証する必要があります。OAuth では認証するユーザーにブラウザでPaylocity との通信を要求します。詳しくは、ヘルプドキュメントのOAuth セクションを参照してください。

   Pay Entry API

   Pay Entry API はPaylocity API の他の部分と完全に分離されています。個別のクライアントID とシークレットを使用し、アカウントへのアクセスを許可するにはPaylocity から明示的にリクエストする必要があります。 Pay Entry API を使用すると、個々の従業員の給与情報を自動的に送信できます。 Pay Entry API によって提供されるものの性質が非常に限られているため、CData では個別のスキーマを提供しないことを選択しましたが、UsePayEntryAPI 接続プロパティを介して有効にできます。

   UsePayEntryAPI をtrue に設定する場合は、CreatePayEntryImportBatch、MergePayEntryImportBatch、Input_TimeEntry、およびOAuth ストアドプロシージャのみ利用できることに注意してください。 製品のその他の機能を使用しようとするとエラーが発生します。また、OAuthAccessToken を個別に保存する必要があります。これは、この接続プロパティを使用するときに異なるOAuthSettingsLocation を設定することを意味します。

3. ［Test Connection］をクリックして値を確認します。

接続プロパティとその機能の説明については、ヘルプドキュメントの［Connection String Options］チャプターを参照してください。

ファイル送信ポートを構成する

ファイル送信ポートは、インサートから返されるId をファイルに書き込みます。以下のステップに従って一方向送信ポートを構成し、受信メッセージをファイルに書きこみます。

1. ［Send Ports］を右クリックし、［Static One-Way Send Port］をクリックします。
2. ［Type］メニューで、［FILE］を選択します。
3. ［Configure］をクリックします。
4. ［DemoInbound］のような、メッセージが書き込まれるフォルダへのパスを［Destination Folder］ボックスに入力します。

アプリケーションを介してBizTalk メッセージをルーティングするフィルタを作成する

以下のステップに従って、アプリケーションで次の関連を定義するフィルタルールを作成します。

• 要請応答送信ポートを、アップデートグラムを含むBizTalk メッセージと関連付けます。
• ファイル送信ポートを、アップデートグラムの実行結果によって作成されたBizTalk メッセージと関連付けます。

1. 要請応答送信ポートのプロパティで、［Filters］をクリックし、以下の値を設定します。

   • プロパティ…メニューから、［BTS.InboundTransportLocation］を選択します。
   • 値…一方向の受信場所のURLを入力します。（この例では、［"C:\DemoOutbound\*.xml］を使用しています。）

2. 一方向送信ポートのプロパティで、［Filters］をクリックし、以下の値を設定します。

   • プロパティ…メニューから、［BTS.SPName］を選択します。
   • 値…要請応答送信ポートの（URL ではなく）名前を入力します。

ロケーションとポートをエンリストして有効にする

BizTalk アプリケーションを起動するときに以下の手順に従い、アップデートグラムが受信場所によって確実に取得されるようにします。

1. 要請応答送信ポートを右クリックし、［Start］をクリックします。これにより、送信ポートも登録されます。
2. 一方向送信ポートを右クリックし、［Start］をクリックします。これにより、送信ポートも登録されます。
3. 受信場所を右クリックし、［Enable］をクリックします。

受信場所用に構成したフォルダに、アップデートグラムを複製することができます。

一方向送信ポート用に構成したフォルダを開きます。このフォルダは、XML file の新しいId を含みます。メッセージは次の例のようになります。

<table xmlns="http://www.cdata.com/PaylocityProvider" AffectedRows="1"> <row> <Id>0014000001XERBUAA5</Id> </row> </table>

アプリケーションログを表示する

アプリケーションログでエラーメッセージを表示することで、アプリケーションが正常に初期化されたことを素早く確認できます。ログを開くには、［Administration Console］のナビゲーションツリーで［Event Viewer (Local)］ノードを展開します。Windows ログを展開し、［Applications］を選択します。

発生したエラーのリストはここから入手可能です。ここには、システム上のすべてのアプリケーションのエラ-メッセージが含まれるため、エラーメッセージのソースを確認することが必要です。受信場所では、ソースが［CData BizTalk Paylocity Receive Adapter］である必要があります。エラーメッセージの詳細から、エラーの理由を知ることができます。

エラー解消のガイダンスについては、[email protected]/jp にお問い合わせください。