ブログ

はじめに

SAP BTPとSAP SuccessFactorsとの連携で、WebAPIの「OData」で開発されることは少なくないと思います。

※「ODataとは何か」「ODataを使うメリット/デメリット」「主に利用可能なquery options（$metadata, $count, $filter, $select, $orderby, $expand）」については当ブログの別記事である以下の記事をご参照ください。
「【OData】SAPのアドオン開発のデータ連携を簡単に！OData APIについて」

本記事では、上記記事にある一般的な OData API 操作ではなく、SuccessFactorsにおけるMDFオブジェクトへの操作の際に使用するパラメータをいくつか紹介いたします。

MDFオブジェクトとは、SuccessFactorsで用意されているデータモデルを基に、クライアントの要望に沿ってカスタマイズや拡張されるデータオブジェクトのことです。
SAP拡張開発案件においてもSAP BTPとSuccessFactorsとの連携において、MDFオブジェクトへのクエリを行って開発をする場面があると思います。

「SuccessFactors」は人的資本管理のためのクラウドベースのソリューションとして紹介されます。
人的資本管理で管理する情報として、人の経歴、部署の情報などは「いつからいつまで、何をしていた（どういう状態か）」を示す各レコードの「歴」の扱いを正確に行う必要があります。

SAP BTPとSuccessFactorsとの連携での拡張開発の経験の浅い方向けに、MDFオブジェクトにおいて、歴管理のあるエンティティから欲しいレコードを取得する際に扱う基本的なquery optionsのfromDate/toDate、asOfDate、filterParentDateについて解説いたします。
※本記事で解説するクエリオプションは一般的なOdata API操作ではなく、MDF固有の操作のパラメータとなることをご注意ください。

目次

• そもそも歴って？
• fromDate / toDate
• asOfDate
• MCPD（Multi Changes Per Date）について
• filterParentDate

そもそも歴って？

各パラメータの紹介を行う前に、人的資本管理における「歴」が何を指し示しているのかを、Aさんの部署異動の履歴を保存しているエンティティを例に挙げて説明いたします。

①2000/04/01 人事部
②2005/04/01 情報システム部に異動
③2010/04/01 法務部に異動
④2022/04/01 経理部に異動

Aさんの職務履歴には上記の様に、いつからいつまで、どの部署にいたかが記録されています。
このように、部署異動に関する情報を持つエンティティがあった場合、Aさんは上記の4つの歴を持っていると見ることができます。

本記事ではこのように有効な期間を各時点で区切っているエンティティのレコードをそれぞれ歴、そうしたエンティティを歴管理のあるエンティティと呼び、パラメータの使い分け方について、上記Aさんの歴を基に解説いたします。

fromDate / toDate

『2005年から2020年までの間、Aさんが所属していた部署を全て確認したい！』
⇒fromDate/toDateで確認しよう！

　

例）GET https://sandbox.api.sap.com/successfactors/odata/v2/EntityA?fromDate=2005-04-01&toDate=2020-12-31

fromDate, toDateはそれぞれ指定した期間内に有効なレコードを全て取得します。
fromDate / toDateはそれぞれ単一で指定することも可能ですが、asOfDateと併用することはできません。

fromDate=yyyy-mm-ddの形で設定し、指定日付以降で有効な全てのデータを取得、toDate=yyyy-mm-ddで、指定日付以前で有効な全てのデータを取得します。
上記リクエストを実行する場合、Aさんの2005/01/01～2020/12/31に在籍していた部署の情報（歴）、つまり①と②と③のレコードが取得可能です。

　

asOfDate

『2013年の10月ごろ、Aさんがどこの部署に所属していたかを知りたい！』
⇒asOfDateで確認しよう！

　

　

使用形式：
asOfDate = yyyy-MM-dd

例）GET https://sandbox.api.sap.com/successfactors/odata/v2/EntityA?asOfDate=2013-10-01

asOfDateは指定した日付時点での有効なレコードを取得する際に使われます。
特徴としては、単一のレコードを取得すること、そして対象EntityがMCPD（※）の場合、レコードの連番（SequenceNumber）が最大のものを取得するという点が挙げられます。

上記リクエストを実行した場合、2013/10/01時点で有効なレコード（所属している部署）、つまり③のレコードが取得できます。
また「fromDate/toDate」との併用はできません。
※「fromDate/toDate」, 「asOfDate」を付けずに実行すると「asOfDate=現在の日付」で実行されます。

　

※MCPD（Multi Changes Per Date）について

一部のエンティティについては、同日に複数の変更がある場合、上書きではなく各更新毎に連番（SequenceNumber）が割り当てられ、同日の変更全ての履歴が保存されます。そのようなエンティティの属性はMCPDと称されます。

MCPDについての留意点は、その日の歴を全て取得したいのであれば「fromDate / toDate」を指定し、その日の最後の更新（連番が最大の履歴）だけ見れば良いのであれば「asOfDate」を指定することで、確認したい歴のみ確認可能となります。

　

上記画像を例とすると、Aさんは2005/04/01に部署をA事業部と情報システム部を兼務することとなったため、下記のような歴を持っています。

①2000/04/01 人事部　　　　　連番（sequenceNumber）1
②2005/04/01 Ａ事業部　　　　連番（sequenceNumber）1
　2005/04/01 情報システム部　連番（sequenceNumber）2
③2010/04/01 法務部に異動　　連番（sequenceNumber）1
④2022/04/01 経理部に異動　　連番（sequenceNumber）1

この状態でasOfDate=2006/04/01を指定した場合、取得できるのは2006/04/01時点で有効なレコードのうち、連番が最大のものとなるため、取得できるのは②-2.情報システム部所属の歴となります。

Ａ事業部の歴も確認したい場合は、「fromDate/toDate」を使用することで連番1のレコードも取得することが可能です。

　

filterParentDate

『親子関係があるエンティティのうち、子エンティティのレコードがうまく取得できない・・・。』
⇒filterParentDateをtrueにしよう！

　

上図のように、親子関係にあるエンティティのうち、子にあたるエンティティは親エンティティの有効開始日情報を持っていますが、上述してきた「fromDate/toDate」, 「asOfDate」だけで使用することはできません。

子エンティティを対象として「fromDate/toDate」, 「asOfDate」を使用してレコードを取得する場合に必要なパラメータが「filterParentDate」です。

子エンティティへのクエリについては、「filterParentDate=true」を指定しない場合「asOfDate」「fromDate/toDate」のいずれも無効化されます。

・filterParentDate指定なし / toDate = 2013-04-01とした場合

例）GET https://sandbox.api.sap.com/successfactors/odata/v2/ChildEntity?toDate=2013-04-01

上記リクエストを実行した場合、toDateは無効化され、子エンティティの有効な全てのレコード（1.~4.のレコード）が取得されます。

　

・filterParentDate指定あり / toDate = 2013-04-01とした場合

例）GET https://sandbox.api.sap.com/successfactors/odata/v2/ChildEntity?toDate=2013-04-01&filterParentDate=true

上記リクエストを実行した場合、日付パラメータ（toDate = 2013-04-01）は正常に機能するため、指定した日付までの期間で有効なレコード（1.~3.のレコード）が取得されます。

　

・filterParentDate指定ありのみの場合

例）GET https://sandbox.api.sap.com/successfactors/odata/v2/ChildEntity?filterParentDate=true

上記リクエストを実行した場合、親エンティティの現在日付で有効なレコード（4.のレコード）が取得されます。
つまり、こちらはfilterParentDate=true&asOfDate=現在日付と同じ挙動となります。

おわりに

Odataを扱うにあたり、歴管理のあるエンティティの取得方法は正確に理解しておく必要があります。しかし、それぞれの扱い方の理解は初学者にとって最初につまずく箇所となるのではないでしょうか。

冒頭で解説した通り、SAP BTPとSuccessFactorsの連携を用いたアドオン拡張開発にて、パフォーマンスの良いPGMを作るためにも、必ず押さえておく必要のあるパラメータです。

実際に私が開発に携わっているSAP BTP上のアドオン開発においても「誰の」「いつの」レコードであるかどうかは重要なファクターです。しかし、学習を始めたての頃はリファレンスを見るだけでは腹落ちしない部分もあり、何度もリファレンスを読み返しては試行錯誤を繰り返していました。

本記事が過去の私のようなSAP初学者の方の「リファレンスが英語ばかりで頭に入らない」「それぞれのパラメータの違いがわからない」というお悩みの一助となり、技術理解への1つ目のステップとなり、ひいては技術者としての生産性の向上につながることを願います。