UKG Pro HCM と UKG Pro Workforce Management 向けの新しい CData API プロファイル


UKG Pro Human Capital Management（HCM）と UKG Pro Workforce Management（WFM）を併用している組織では、従業員に関する記録が 2 か所に分かれて管理されています。UKG Pro HCM が管理するのは人事記録で、職務、組織階層、報酬、PTO（有給休暇）プランなどが含まれます。一方、UKG Pro WFM が管理するのは勤怠記録で、タイムカード、打刻、シフト、給与コードなどが含まれます。製品ごとに API、認証方式、識別子が異なるため、結果を手作業でつなぎ合わせているチームも少なくありません。この記事では、CData JDBC Driver for API を使って両製品からデータを取得し、両者に共通する従業員番号をキーに、人事記録上の勤務時間と実際の支給対象時間を照合する方法をご紹介します。

CData API Driver と API プロファイルについて

CData API Driver は、拡大を続ける API や Web サービスのカタログに SQL でアクセスできる単一のドライバーです。サービスごとに個別のドライバーを用意する代わりに、API プロファイルを使用します。API プロファイルは、1 つの API について、オブジェクト、フィールド、操作に加え、認証方法やページングの方法を定義した小さなファイルです。CData では、CRM、マーケティング、E コマース、会計、コラボレーションなど、さまざまなカテゴリのプロファイルを提供しています。

プロファイルを使うには、ドライバーの Profile プロパティにプロファイルファイルのパスを指定し、そのプロファイルで必要な接続プロパティを設定します。あとはドライバーが次の処理を引き受けます。

  • SQL-92 のサポート：文字列関数、日付関数、数値関数、JOIN、集計に対応
  • フィルタのプッシュダウン：API がサポートするフィルタは、取得後に適用するのではなく API 側に送信
  • 認証とトークンの更新：各 API で使われる OAuth フローにも対応
  • ページング：API がサポートしている場合に対応

API Driver は、他の CData ドライバーと同じく JDBC、ODBC、ADO.NET、Python の各エディションに加え、Excel、Power BI、SSIS 向けの連携製品としても提供しています。プロファイルはどのエディションでも同じように動作するため、この記事の手順はお使いのエディションでもそのまま応用できます。この記事では CData JDBC Driver for API を使用します。

ドライバーとプロファイルのセットアップ

  1. CData JDBC Driver for API をダウンロードしてインストールします。
  2. CData API プロファイルから UKGProHCM.apip と UKGProWFM.apip をダウンロードします。

UKG Pro HCM に接続する

UKG Pro HCM の認証には、ユーザー名、パスワード、顧客 API キーを使用します。プロファイルはこのキーを US-CUSTOMER-API-KEY ヘッダーとしてすべてのリクエストに付与するため、キーがないとドライバーは UKG に接続できません。

  1. ドライバーの JAR ファイルをダブルクリックして接続ダイアログを開き、Profile に UKGProHCM.apip のパスを設定します。

  2. AuthScheme を Basic に設定します。

  3. UKG Pro HCM の User と Password を入力します。

  4. ProfileSettings に、テナントのホストと顧客 API キーをセミコロン区切りで入力します。

    Host=yourcompany.ultipro.com;CustomerAPIKey=your_customer_api_key
    ドライバーで UKG Pro HCM の接続を設定

  5. Test Connect をクリックします。成功メッセージが表示されれば、ドライバーが UKG に接続し、認証が完了しています。

    UKG Pro HCM の接続テストに成功

接続文字列全体は次のようになります。

Profile=C:\profiles\UKGProHCM.apip;AuthScheme=Basic;User=<user>;Password=<password>;ProfileSettings='Host=<yourcompany>.ultipro.com;CustomerAPIKey=<customer api key>';

オブジェクトの一覧はプロファイルファイルから読み込まれるため、ドライバーが UKG に接続する前から表示されます。認証情報が正しいかどうかは、接続テストを実行するか、最初にデータを取得した時点で初めて確認できます。

UKG Pro WFM に接続する

UKG Pro WFM では、OAuth 2.0 のリソースオーナーパスワードグラントを使用します。ブラウザでのサインイン手順はなく、ドライバーが WFM のユーザー名、パスワード、クライアント ID、クライアントシークレットを使って、直接アクセストークンを取得します。

  1. もう一度接続ダイアログを開き、Profile に UKGProWFM.apip のパスを設定します。

  2. AuthScheme を OAuthPassword に設定します。

  3. UKG Pro WFM の API アプリケーション用に発行された OAuthClientId と OAuthClientSecret を入力します。

  4. テナントの Host、User、Password を入力します。

    Host=<yourcompany>.mykronos.com;User=<user>;Password=<password>
    ドライバーで UKG Pro WFM の接続を設定

  5. Test Connect をクリックします。

    UKG Pro WFM の接続テストに成功

接続文字列全体は次のようになります。

Profile=C:\profiles\UKGProWFM.apip;AuthScheme=OAuthPassword;OAuthClientId=<client id>;OAuthClientSecret=<client secret>;ProfileSettings='Host=<yourcompany>.mykronos.com;User=<user>;Password=<password>';

UKG Pro HCM と UKG Pro WFM からデータを取得する

接続に成功したら、いよいよデータを取得していきましょう。ドライバーの接続ダイアログは接続テスト用で、ステートメントの実行には DBeaver などの SQL クライアントを使用します。SQL クライアントに CData JDBC Driver for API を追加し、上記の接続文字列を使って製品ごとに接続を 1 つずつ作成します。あとは、各ステートメントを対応する製品の接続で実行します。

UKG Pro HCM から従業員レコードを取得する

まずは、人員数、離職率、組織に関するレポートの起点となる EmploymentDetails から始めましょう。DBeaver でデータを取得する手順は次のとおりです。

  1. Database Navigator で HCM の接続を展開し、オブジェクトを表示します。
  2. その接続で SQL Editor を開き、以下のステートメントを貼り付けます。
  3. ステートメントを実行します。結果の下にある行数制限ボックスで、返されるレコード数の上限を設定できます。
SELECT [EmployeeNumber], [PrimaryJobCode], [SalaryOrHourly],
       [FullTimeOrPartTimeCode], [ScheduledWorkHrs], [PayPeriod]
FROM [EmploymentDetails]
WHERE [EmployeeStatusCode] = 'A'

このステートメントは、在籍中の各従業員について、人事記録上の職務、給与形態、フルタイム／パートタイムの区分、所定労働時間を返します。

DBeaver で UKG Pro HCM から従業員レコードを取得

この結果に含まれる EmployeeNumber の値は控えておきましょう。UKG Pro WFM では同じ番号を PersonNumber として使用しているため、このセクションの後半で両製品のレコードを照合する際に役立ちます。

UKG Pro WFM からタイムカードを取得する

UKG Pro WFM のデータは、「人」と「期間」を軸に構成されています。タイムカードを読み取るには、まず給与計算期間を特定し、従業員番号からその人の WFM ID を調べたうえで、該当する人と期間のタイムカードを取得します。DBeaver の WFM 接続で、次の 3 つのステートメントを 1 つずつ実行してみてください。実行前に、プレースホルダーをすべて実際の値に置き換えておきましょう。

  1. 指定した日付を含む給与計算期間を特定します。日付には、テナント内で締めが完了している給与計算期間の日付を使用してください。

    SELECT [SpanStartDate], [SpanEndDate], [PeriodDays]
FROM [PayPeriods] WHERE [Date] = '2026-09-26'

  2. HCM の結果から取得した従業員番号を、WFM のパーソン ID に変換します。

    SELECT [PersonId] FROM [PersonInformation] WHERE [PersonNumber] = '<employee number>'

  3. 手順 2 の PersonId と、手順 1 の SpanStartDate、SpanEndDate を使って、タイムカードを取得します。

    SELECT [Totals], [ScheduleShifts] FROM [Timecards]
WHERE [PersonId] = '<person id>'
  AND [StartDate] = '<SpanStartDate>' AND [EndDate] = '<SpanEndDate>'
DBeaver で UKG Pro WFM からタイムカードを取得

結果の Totals フィールドには、Regular、All Worked Hours、All Paid Hours など、給与コードごとの期間合計が、数量と種別とともに格納されています。ScheduleShifts フィールドには、予定されたシフトが開始時刻・終了時刻とともに格納されています。

両製品のレコードを照合する

UKG Pro HCM と UKG Pro WFM は従業員番号を共有しており、HCM の EmployeeNumber が WFM の PersonNumber に対応します。プロファイルはそれぞれ別の接続で動作するため、各接続から個別にデータを取得し、従業員番号でレコードを照合します。たとえば、HCM の ScheduledWorkHrs と WFM の All Paid Hours を比較すれば、人事記録が実際の支給対象時間を反映しているかどうかを確認できます。

CData で UKG のデータ取得を始めましょう

CData JDBC Driver for API を使えば、1 つのドライバーから標準 SQL で、UKG Pro HCM の 23 オブジェクトと UKG Pro WFM の 22 オブジェクトのデータを取得できます。ぜひ30日間の無償トライアルをダウンロードし、2 つのプロファイルを追加して、最初のレコードを取得してみてください。両製品は従業員番号を共有しているため、それぞれの接続でリクエストを 1 回ずつ実行するだけで、人事データと勤怠データの比較を始められます。ご不明な点があれば、お気軽にサポートチームまでお問い合わせください。

In this article

Related articles