TIBCO Data Virtualization で Paylocity のデータ にリアルタイムアクセスする方法
TIBCO Data Virtualization（TDV）は、複数の多様なデータソースへのアクセスを一元管理するエンタープライズデータ仮想化ソリューションです。CData TIBCO DV Adapter for Paylocity と組み合わせることで、TIBCO Data Virtualization 内からPaylocity のデータに直接フェデレーテッドアクセスが可能になります。この記事では、アダプターのデプロイと Paylocity に基づく新しいデータソースの作成手順を解説します。
CData TIBCO DV Adapter は、最適化されたデータ処理機能が組み込まれており、Paylocity のデータ とのインタラクションにおいて比類のないパフォーマンスを発揮します。Paylocity に対して複雑な SQL クエリを発行すると、アダプターはフィルタや集計などサポートされている SQL 操作を直接 Paylocity にプッシュします。組み込みの動的メタデータクエリにより、ネイティブのデータ型を使用してPaylocity のデータを操作・分析できます。
Paylocity TIBCO DV Adapter のデプロイ
コンソールで、TDV Server のインストールディレクトリ内の bin フォルダに移動します。現在のバージョンのアダプターがインストールされている場合は、先にアンデプロイする必要があります。
.\server_util.bat -server localhost -user admin -password ******** -undeploy -version 1 -name Paylocity
CData TIBCO DV Adapter をローカルフォルダに解凍し、解凍した場所から JAR ファイル（tdv.paylocity.jar）をサーバーにデプロイします。
.\server_util.bat -server localhost -user admin -password ******** -deploy -package /PATH/TO/tdv.paylocity.jar
新しい JAR ファイルが正しくロードされるように、サーバーの再起動が必要な場合があります。再起動は、C:\Program Files\TIBCO\TDV Server <version>\bin にある composite.bat スクリプトを実行して行えます。サーバーを再起動した後は、TDV Studio への再認証が必要です。
再起動コマンドの例
.\composite.bat monitor restart
OAuth を使用して Paylocity で認証する
Paylocity は OAuth プロトコルを使用して認証を行いますが、TDV Studio は内部でブラウザベースの認証をサポートしていないため、OAuth トークンを取得するための簡単な Java アプリケーションを作成して実行する必要があります。取得したトークンは、アダプターから直接 Paylocity に接続するために使用されます。
Create the Java Application
- Create a new Java file with preferred name for example GenOAuthSettings.java. This Java file leverages the PaylocityOAuth class contained within the TDV Adapter JAR to initiate a test connection and perform the required OAuth authentication flow
- Copy and insert the following code into the .java file:
- Place the .java file in the same directory as the tdv.paylocity.jar file. This is required to prevent classpath resolution errors during compilation and execution
public class GenOAuthSettings {
public static void main(String[] args) {
try {
if (args.length != 2) {
throw new Exception("Input must have two arguments: 'data source', 'connection string'");
}
String source = args[0].replace(" ", "").toLowerCase();
String connectionString = args[1];
String prefix;
if (source.equals("paylocity")) {
prefix = "jdbc:paylocity:";
com.cdata.cis.paylocity.PaylocityOAuth oauth = new com.cdata.cis.paylocity.PaylocityOAuth();
if (!connectionString.startsWith(prefix)) connectionString = prefix + connectionString;
oauth.generateOAuthSettingsFile(connectionString);
}
// More sources can be added below using the same format. You must add the import statement and ensure the jar file resides in the classpath
// else if (source.equals("googlebigquery") || source.equals("bigquery")) {
// prefix = "jdbc:googlebigquery:";
//
// com.cdata.cis.googlebigquery.GoogleBigQueryOAuth oauth = new com.cdata.cis.googlebigquery.GoogleBigQueryOAuth();
//
// if (!connectionString.startsWith(prefix)) connectionString = prefix + connectionString;
// oauth.generateOAuthSettingsFile(connectionString);
// }
else {
throw new Exception("Data Source not supported. Available Data Sources: Paylocity");
}
System.out.println("Test Connection Successful!");
} catch (Exception e) {
e.printStackTrace();
}
}
}
Build and run the Java Application
- Open Console and navigate to the directory containing the .java file and adapter jar
- Compile the Java file using the following command:
- Execute the application using one of the following commands:
javac -cp .;tdv.paylocity.jar GenOAuthSettings.java
java -cp .;tdv.paylocity.jar GenOAuthSettings "Paylocity" "connection string"
This command initiates the OAuth authentication flow and generates the OAuth settings file at the location specified in the OAuthSettingsLocation parameter. Once you deploy the adapter and authenticate, you can create a new data source for Paylocity in TDV Studio.
TDV Studio で Paylocity データソースを作成する
CData TIBCO DV Adapter for Paylocity を使用すると、Paylocity 用のデータソースを簡単に作成し、データソースをイントロスペクトしてリソースを TDV に追加できます。
データソースの作成
- データソースを追加するフォルダを右クリックし、New -> New Data Source を選択します。
- アダプター（例：Paylocity）が表示されるまでスクロールし、Next をクリックします。
- データソースに名前を付けます（例：CData Paylocity Source）。
必要な接続プロパティを入力します。
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 を設定することを意味します。
NOTE：DV Adapter の OAuthSettingsLocation プロパティには、OAuth 認証（上記参照）を実行したときと同じ値を設定してください。
- RSAPublicKey：Paylocity アカウントでRSA 暗号化が有効になっている場合は、Paylocity に関連付けられたRSA キーを設定。
- Create & Close をクリックします。
データソースのイントロスペクト
データソースを作成したら、右クリックして Open を選択することでデータソースをイントロスペクトできます。ダッシュボードで Add/Remove Resources をクリックし、データソースの一部として含めるテーブル、ビュー、ストアドプロシージャを選択します。Next をクリックし、Finish をクリックして、選択した Paylocity のテーブル、ビュー、ストアドプロシージャをリソースとして追加します。
After creating and introspecting the data source, you are ready to work with Paylocity のデータ in TIBCO Data Virtualization just like you would any other relational data source. You can create views, query using SQL, publish the data source, and more.
データソースを作成してイントロスペクトしたら、他のリレーショナルデータソースと同様に TIBCO Data Virtualization でPaylocity のデータを操作できるようになります。ビューの作成、SQL によるクエリ、データソースの公開など、さまざまな操作が可能です。