CData JDBC Driver for Paylocity はじめに：インストールから接続まで

このガイドでは、CData JDBC Driver for Paylocity を使い始めるために必要な情報をすべて説明します。ドライバーのインストール方法とライセンス認証の手順から、最初の接続設定、そして Java アプリケーションで Paylocity のデータ を活用するための次のステップまでをご紹介します。

インストールとライセンス

ドライバーのインストール

1. CData の Web サイトから JDBC ドライバーのインストーラーをダウンロードします。
2. インストーラーを実行し、インストールウィザードに従って進めます。
3. ドライバーは次の場所にインストールされます： C:\Program Files\CData\CData JDBC Driver for Paylocity 20xx\lib\
4. JAR ファイルの名前は cdata.jdbc.paylocity.jar です。

インストールが完了したら、IDE やビルドツールを使用して、JAR ファイルを Java プロジェクトのクラスパスに追加できます。

ライセンスの有効化

CData Orders チームから送付されたメールでライセンスキーをお持ちのはずです。英数字のライセンスキーは次のような形式です：

Windows

Windows では、主なライセンス認証方法はライセンスファイルによる方法です。JDBC ドライバーをインストールすると、ライセンスファイルが自動的に作成され、ドライバーのインストールディレクトリに保存されます。アプリケーションで JAR がロードされると、ドライバーはこのライセンスファイルを自動的に検出して使用します。

ライセンスを手動で有効化または更新する必要がある場合は：

1. インストールディレクトリにあるライセンスファイルを見つけます。
2. ライセンスファイルをライセンスキーで更新します。
3. ドライバーは次回の接続時に更新されたライセンスを自動的に使用します。

macOS/Linux

JAR のインストールディレクトリに移動し、lib フォルダーで次のコマンドを実行します： java -jar cdata.jdbc.paylocity.jar --license

プロンプトに従ってライセンスキーを入力します。これにより、インストールディレクトリにライセンスファイルが作成され、ドライバーがライセンス認証に使用します。

ライセンスファイルの設定方法について詳しくは、ヘルプドキュメントのGetting StartedサブページにあるLicensingセクションをご覧ください。

ライセンスに関するよくある質問

複数のマシンでライセンスを使用できますか？
はい、サブスクリプションのレベルによります。詳細については、注文確認書をご確認いただくか、担当営業にお問い合わせください。担当営業が不明な場合は、[email protected]までご連絡ください。

ライセンスキーを紛失しました。再発行は可能ですか？
注文番号を記載して[email protected]にメールをお送りください。ライセンスキーを再送いたします。

ライセンスを別のマシンに移行できますか？
はい、可能です。ライセンスを別のマシンに移行する際は、以下のリンクからライセンス移行リクエストを提出する必要があります：

https://jp.cdata.com/contact/

ライセンス移行リクエストが提出され、正常に処理されると、プロダクトキーに新しいアクティベーションが追加され、別のマシンで完全なライセンスを有効化できます。この処理が完了すると、以前のマシンのライセンスは無効になります。

ライセンスファイルの代わりに RTK を使用すべき場合は？
コンテナ、クラウドインスタンス、または複数のマシンにアプリケーションを配布する場合など、マシン/ノード ID が動的に変更される環境にデプロイする場合は RTK を使用してください。

ライセンスに関するその他のご質問は、[email protected]までお問い合わせください。ライセンスの確認とアップグレードは、セルフサービスポータル（portal.cdata.com）から行えるようになりました。

接続の設定

ドライバーのインストールとライセンス認証が完了したら、Paylocity への接続を設定できます。JDBC 接続は、接続 URL（接続文字列とも呼ばれます）を使用して確立されます。

JDBC 接続 URL の理解

CData ドライバーの JDBC 接続 URL は次のパターンに従います：

接続 URL の構築

おすすめ：内蔵の接続文字列デザイナーを使用

JDBC ドライバーには、必要なすべての接続プロパティを含む正しい JDBC URL を構築するための接続文字列デザイナーツールが含まれています。

接続文字列デザイナーの起動方法：

1. ドライバーのインストールディレクトリに移動します： C:\Program Files\CData\CData JDBC Driver for Paylocity 20xx\lib\
2. JAR ファイルをダブルクリックします：cdata.jdbc.paylocity.jar
   または
   コマンドラインから実行します： java -jar cdata.jdbc.paylocity.jar
3. 接続文字列デザイナーが起動します。
4. 表示されるフィールドに接続プロパティを入力します。
5. Test Connectionをクリックして設定を確認します。
6. デザイナーから生成された JDBC URL をコピーします。

接続文字列デザイナーを使用すると、正しい構文で記述でき、Paylocity で使用可能なすべての接続プロパティを確認できます。

ドライバークラス名

IntelliJ IDEA、Eclipse、DBeaver などの IDE やその他のツールで JDBC ドライバーを設定する際には、ドライバークラス名を指定する必要があります：

接続プロパティの設定

必要な接続プロパティは、データソースによって異なります。

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 を設定することを意味します。

Paylocity で使用可能なすべての接続プロパティの詳細については、ヘルプドキュメントのEstablishing a Connectionセクションをご覧ください。

接続のテスト

接続は次の方法でテストできます：

接続文字列デザイナーでのテスト

プロパティを入力後、Test Connectionボタンをクリックします。テストが成功すれば、認証情報と接続設定が正しいことが確認できます。

アプリケーションでのテスト

アプリケーションでドライバー JAR を特定の場所に移動する必要がある場合は、今すぐ移動し、JAR がアプリケーションのクラスパスに含まれていることを確認してください。また、ライセンス認証のために .lic ファイルも同じ場所に移動してください。

注意： DBeaver などの多くの JDBC 対応ツールでは、Test Connection 機能を使用する際にプロバイダーへのライブリクエストは実際には送信されません。 これは表面的なテストのみで、基本的に JAR ファイルが基本レベルで機能することをチェックするだけです。 JDBC 対応ツールを使用する場合は、有効な接続テストを確認するために ConnectOnOpen プロパティを True に設定する必要があります。

IDE で JDBC ドライバーを使用している場合は、簡単なクエリを実行して接続を確認できます：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

String url = "jdbc:paylocity:OAuthClientID=YourClientId;OAuthClientSecret=YourClientSecret;RSAPublicKey=YourRSAPubKey;Key=YourKey;IV=YourIV;
Connection conn = DriverManager.getConnection(url);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM Employee LIMIT 1");

if (rs.next()) {
    System.out.println("Connection successful!");
}

接続エラーが発生した場合は：

1. 接続文字列デザイナーを使用して、接続プロパティが正しいことを確認します。
2. ドライバー JAR がアプリケーションのクラスパスに含まれていることを確認します。
3. エラーメッセージを確認し、具体的なガイダンスを参照します。
4. トラブルシューティングのサポートが必要な場合は、エラーの詳細を添えて[email protected]にお問い合わせください。

よくある接続の問題

ドライバーが見つからない / ClassNotFoundException

解決方法：JDBC ドライバー JAR（cdata.jdbc.paylocity.jar）がプロジェクトのクラスパスに正しく追加されていることを確認してください。設定方法は IDE やビルドツールによって異なります。開発環境のドキュメントを参照するか、[email protected]にサポートをお問い合わせください。

認証エラー

解決方法：認証情報が正しく、最新であることを確認してください。接続文字列デザイナーを使用して、アプリケーションに追加する前に認証情報をテストしてください。Paylocity の認証要件の詳細については、ヘルプドキュメントのEstablishing a Connectionセクションをご覧ください。

ネットワーク接続の問題

解決方法：ファイアウォールが必要なポートでの送信接続を許可していることを確認してください。データソースの具体的なポートとファイアウォール要件については、[email protected]にお問い合わせください。

無効な接続文字列フォーマット

解決方法：接続文字列デザイナーを使用して、正しい形式の JDBC URL を生成してください。デザイナーは正しい構文とプロパティ名を保証します。

その他のトラブルシューティングについては、具体的なエラーメッセージを添えて[email protected]にお問い合わせください。

次のステップ

ドライバーのインストール、ライセンス認証、設定が完了したので、CData JDBC ドライバーを活用する次のシナリオをご覧ください：

サポート

サポートが必要な場合は、以下までお問い合わせください：

• テクニカルサポート： [email protected]
• ナレッジベース： CData ナレッジベース
• コミュニティフォーラム： CData コミュニティサイト
• ヘルプドキュメント： ローカルにインストール済み、およびオンラインでも利用可能

よくある質問

インストールとライセンス

• JDBC ドライバーはどこにインストールされますか？
  デフォルトのインストールディレクトリは以下のとおりです：
  Windows： C:\Program Files\CData\CData JDBC Driver for Paylocity \lib
  Mac： /Application/CData JDBC Driver for Paylocity /lib
  Linux： /home//CData/CData JDBC Driver for Paylocity /lib
• ライセンスキーを取得するには？
  ライセンスキーはご購入時にメールで送信されます。再送が必要な場合は、注文番号を添えて[email protected]にお問い合わせください。
• 複数のアプリケーションでライセンスを使用できますか？
  はい、可能です。ライセンスファイルは、マシン上でドライバーを使用するすべての Java アプリケーションで機能します。
• RTK（Runtime Key）を使用すべき場合は？
  コンテナ（Docker/Kubernetes）、クラウドインスタンス、または複数のマシンにアプリケーションを配布する場合など、マシン/ノード ID が動的に変更される環境にデプロイする場合は RTK を使用してください。RTK が必要な場合は、担当営業にお問い合わせください。

接続

• JDBC 接続 URL はどのように構築しますか？
  内蔵の接続文字列デザイナーツールを使用してください。ドライバー JAR をダブルクリックするか、java -jar cdata.jdbc.paylocity.jar を実行してデザイナーを起動します。正しい形式の接続 URL の構築をサポートします。
• ドライバークラス名は何ですか？
  ドライバークラスは次のパターンに従います：cdata.jdbc.paylocity.PaylocityDriver
  IntelliJ IDEA、Eclipse、DBeaver などの IDE でドライバーを設定する際に必要です。
• Paylocity に必要な接続プロパティは何ですか？
  Paylocity の必須およびオプションの接続プロパティの詳細については、ヘルプドキュメントのEstablishing a Connectionセクションをご覧ください。接続文字列デザイナーでも利用可能なすべてのプロパティを確認できます。
• 複数の Paylocity アカウントに接続するには？
  アカウントごとに異なる認証情報を使用して、個別の接続 URL を作成します。アプリケーション内で複数の接続を管理できます。
• 認証情報を安全に保存するには？
  環境変数、設定ファイル、またはシークレット管理システム（AWS Secrets Manager や Azure Key Vault など）を使用してください。認証情報をソースコードにハードコードしないでください。

使用方法と開発

• どの SQL 操作がサポートされていますか？
  サポートされている SQL 操作の一覧については、ヘルプドキュメントのSQL Compliance章をご覧ください。
• マルチスレッドアプリケーションでドライバーを使用できますか？
  はい、可能です。スレッドセーフのための標準的な JDBC のベストプラクティスに従ってください。同時アクセスには接続プーリングを使用してください。
• IDE にドライバーを追加するには？
  JAR ファイル（cdata.jdbc.paylocity.jar）をプロジェクトのクラスパスに追加します。外部 JAR の追加については、IDE のドキュメントを参照してください。ドライバークラス名は：cdata.jdbc.paylocity.PaylocityDriver

パフォーマンスとトラブルシューティング

• クエリが遅いのはなぜですか？
  以下を確認してください：
  • 接続プーリングを使用します。
  • フィルター（WHERE 句）を追加して結果セットのサイズを減らします。
  • クエリの最適化のサポートについては、[email protected]にお問い合わせください。
• トラブルシューティングのためにログを有効にするには？
  接続文字列にログプロパティを追加するか、Logfile プロパティを有効なファイルパスに設定し、Verbosity プロパティを目的のログレベルに設定して、アプリケーションでログを設定します（HTTP リクエストとレスポンスをキャプチャするには Verbosity=3 を推奨します）。ログ設定の詳細については、ヘルプドキュメントのAdvanced Featuresセクションをご覧ください。トラブルシューティングのサポートについては、[email protected]にお問い合わせください。
• どのファイアウォールポートを開く必要がありますか？
  ポート要件はデータソースによって異なります。ほとんどのクラウドアプリケーションは HTTPS（ポート 443）を使用します。必要に応じて、ヘルプドキュメントのAdvanced FeaturesセクションでFirewall & Proxy設定を参照してください。Paylocity の具体的なファイアウォール要件については、[email protected]にお問い合わせください。
• Docker でドライバーをデプロイするには？
  Docker イメージにドライバー JAR を含め、接続文字列で RTK（Runtime Key）を使用してライセンス認証を行います。これにより、動的なコンテナのノード ID が処理されます。
• ClassNotFoundException が発生します。どうすれば修正できますか？
  これは、ドライバー JAR がクラスパスにないことを意味します。JAR ファイルの場所を確認し、IDE またはビルド設定でプロジェクトのクラスパスに追加されていることを確認してください。

全般

• ヘルプドキュメントはどこにありますか？
  ヘルプドキュメントは、インストールディレクトリ内のドライバーとともにインストールされており、CData の Web サイトでも利用可能です。
• ドライバーはどのくらいの頻度で更新されますか？
  CData は年に一度、ドライバーのメジャーバージョンアップデートをリリースしています。最新バージョンについては、アカウントポータルを確認するか、[email protected]にお問い合わせください。
• 特定のユースケースのコード例はありますか？
  はい、あります。ヘルプドキュメントには多数のコード例が含まれています。特定のシナリオの例が必要な場合は、[email protected]にお問い合わせください。

この FAQ で取り上げられていないご質問は、[email protected]にお問い合わせください。