SAP SuccessFactors コネクタ

カテゴリ: API コネクタ

はじめに

本ドキュメントは、mindzieDataDesigner コネクタを SAP SuccessFactors に設定するための手順を説明します。mindzieDataDesigner は mindzieStudio がプロセスマイニングイベントログへデータを変換するための ETL ツールです。SAP SuccessFactors はクラウドベースのヒューマンエクスペリエンスマネジメント（HXM）スイートで、人事、給与、タレントマネジメント、およびワークフォースアナリティクス機能を提供します。本コネクタは、OAuth 2.0 認証を使用した SuccessFactors OData API を利用して人事データを抽出し、プロセスマイニングに活用します。

概要

SAP SuccessFactors コネクタは OData v2 API を使用して、SuccessFactors のデータへ安全な読み取り専用アクセスを提供します。本コネクタは、X.509 証明書を用いた SAML 2.0 ベアラーアサーションによる OAuth 2.0 認証をサポートしており、サーバー間統合に推奨される認証方式です。

主な機能:

• Employee Central データの抽出（従業員プロフィール、雇用履歴、組織構造）
• 勤怠管理、給与、タレントデータへのアクセス
• 読み取り専用アクセスによるデータ整合性の確保
• X.509 証明書による安全な OAuth 2.0 認証

システム要件

• API アクセスが有効化された SAP SuccessFactors インスタンス
• SuccessFactors 管理センターの管理者アクセス
• API ユーザーおよび OAuth アプリケーションの作成・管理権限

前提条件

コネクタを設定する前に、以下を用意してください：

• 管理センターアクセス: SuccessFactors 管理センターへのアクセス権限
• ユーザー管理: 技術/API ユーザー作成権限
• OAuth 設定: OAuth2 クライアントアプリケーション登録権限
• ロールベースの権限（RBP）: 権限グループおよびロールの作成・割当権限
• 証明書管理: X.509 証明書の生成または取得権限

mindzie に必要な資格情報

設定完了後、以下の資格情報を mindzie に提供してください：

資格情報	説明	例
Company ID	SuccessFactors の会社識別子	mycompanyPROD
API サーバー URL	データセンターの OData API エンドポイント	https://api15.sapsf.com
技術ユーザーID	API サービスアカウントのユーザー名	mindzie_api_user
API キー	OAuth アプリケーション登録時のクライアントID	NGYzNzg1YjctZDM4...
秘密鍵	X.509 証明書の秘密鍵（Certificate.pem）	（PEM ファイルの内容）

ステップ 1: API サーバー URL の特定

SAP SuccessFactors は複数のデータセンターを利用しています。API サーバー URL はご利用のインスタンスがホストされるデータセンターによって異なります。

データセンターと API URL の対応表

データセンター	ロケーション	API サーバー URL
DC2	アムステルダム	https://api2.successfactors.eu
DC4	アッシュバーン	https://api4.successfactors.com
DC5	シドニー	https://api5.successfactors.com
DC8	フランクフルト	https://api8.successfactors.eu
DC10	アッシュバーン（米国政府向け）	https://api10.successfactors.com
DC12	アムステルダム	https://api012.successfactors.eu
DC15	上海	https://api15.sapsf.cn
DC17	アッシュバーン	https://api17.sapsf.com
DC18	ロット	https://api18.sapsf.eu
DC19	シドニー	https://api19.sapsf.com
DC20	東京	https://api20.sapsf.com
DC22	リヤド	https://api22.sapsf.com
DC23	モスクワ	https://api23.sapsf.com
DC24	フランクフルト	https://api24.sapsf.eu
DC25	UAE	https://api25.sapsf.com
DC26	シンガポール	https://api26.sapsf.com
DC27	ムンバイ	https://api27.sapsf.com
DC28	カナダ	https://api28.sapsf.com

データセンターを特定する方法:

1. SuccessFactors にログイン
2. ブラウザの URL を確認 - 通常、ドメインにデータセンターが示されています（例: performancemanager4.successfactors.com は DC4）
3. または SuccessFactors 管理者にお問い合わせください

ステップ 2: Company ID を特定

1. SAP SuccessFactors 管理センターにログイン
2. Company Settings または Company System and Logo Settings に移動
3. ここで Company ID を確認できます
4. 通常は mycompanyPROD や ACME_Corp_Production のような文字列です

別の方法:

• SuccessFactors のログイン URL に会社 ID が含まれている場合があります
• SuccessFactors 管理者にお問い合わせください

ステップ 3: 技術 API ユーザーの作成

mindzie 統合用の専用サービスアカウントを作成します。このユーザーは対話的ログインには使用しません。

1. 管理センター -> 社員管理（Manage Employees） に移動
2. 新しい社員を追加（Add New Employee） または 新しいユーザーを追加（Add New User） をクリック
3. 必要項目を入力：
   • ユーザー名: mindzie_api_user（任意の命名規則で可）
   • 名: mindzie
   • 姓: API Service
   • メール: 管理されたサービスアカウントのメールアドレス
4. 安全なパスワードを設定（初期設定時のみ使用）
5. 重要: インスタンスがサポートしていれば、このユーザーを「技術ユーザー」または「サービスアカウント」として識別してください
6. ユーザーを保存

注意: ユーザー名は Technical User ID として mindzie に提供します。

ステップ 4: 権限グループの作成

API アクセス権限を管理するため、権限グループを作成します。

1. 管理センター -> 権限グループ管理（Manage Permission Groups） に移動
2. 新規作成（Create New） をクリックし、権限グループを作成
3. グループ設定：
   • グループ名: mindzie_API_Access（任意）
   • 説明: mindzie プロセスマイニング API アクセス用権限グループ
4. ステップ 3 で作成した技術ユーザーをこのグループに追加
5. グループを保存

ステップ 5: 読み取り専用権限ロールの作成

プロセスマイニングに必要なデータへの読み取り専用アクセスを付与するロールを作成します。

1. 管理センター -> 権限ロール管理（Manage Permission Roles） に移動

2. 新規作成（Create New） をクリックし、ロールを作成

3. ロール設定：

   • ロール名: mindzie_ReadOnly_Role
   • 説明: mindzie プロセスマイニング統合用 読み取り専用アクセス

4. 権限グループの割当: ステップ 4 で作成した権限グループを割り当て

5. 権限の設定: 分析対象のデータに応じて以下の権限を有効化してください

管理者権限

権限	説明
OData API への管理者アクセス	API アクセスに必要
メタデータフレームワークへの管理者アクセス	エンティティメタデータへのアクセス

ユーザー権限

権限	説明
Employee Central OData API	Employee Central データアクセス
勤怠管理 OData API	勤務時間データアクセス
報酬 OData API	報酬データアクセス

従業員データ権限

権限	説明
従業員データ - 表示	従業員プロフィール情報の閲覧
雇用詳細 - 表示	雇用履歴の閲覧
職務情報 - 表示	職務とポジションデータの閲覧
組織データ - 表示	組織構造の閲覧
個人情報 - 表示	個人情報の閲覧
報酬情報 - 表示	給与および報酬データの閲覧

注意: プロセスマイニングの利用ケースに必要な最小限の権限のみを付与してください。必要な権限は利用する SuccessFactors モジュールや分析対象データにより異なります。

6. ロールを保存

ステップ 6: OAuth2 クライアントアプリケーションの登録

安全な API 認証のために OAuth2 クライアントアプリケーションを登録します。

6.1 X.509 証明書の生成

OAuth 認証には X.509 証明書が必要です。既存の企業証明書を使うか、自己署名証明書を生成してください。

自己署名証明書を生成する例（OpenSSL 使用）：

# 2年間有効な秘密鍵と証明書の生成
openssl req -newkey rsa:2048 -nodes -keyout private_key.pem -x509 -days 730 -out certificate.pem -subj "/CN=mindzie-sf-integration/O=Your Company/C=US"

重要: 秘密鍵（private_key.pem）は厳重に管理してください。mindzie に提供する必要があります。

6.2 OAuth アプリケーションの登録

1. 管理センター -> OAuth2 クライアントアプリケーション管理 に移動

2. クライアントアプリケーション登録（Register Client Application） をクリック

3. アプリケーション設定：

   • アプリケーション名: mindzie Process Mining Integration
   • 説明: mindzie データ抽出用 OAuth2 クライアント
   • アプリケーション URL: https://mindzie.com（mindzie 指定の場合）

4. X.509 証明書のアップロード:

   • 上記で生成した certificate.pem ファイルをアップロード
   • 証明書は SAML アサーション署名に使用されます

5. API アクセス設定:

   • アプリケーションがアクセス可能な API を選択
   • 最低でも OData API を有効化してください

6. 登録（Register） をクリックして登録を完了

7. API キーの記録: 登録後、「API キー」（クライアント ID）が表示されます。これは mindzie に提供します。

ステップ 7: mindzie に資格情報を提供

以下の資格情報を安全に mindzie に送付してください：

資格情報	値
Company ID	ステップ 2 で特定した会社識別子
API サーバー URL	ステップ 1 で特定したデータセンター URL
技術ユーザー ID	ステップ 3 で作成したユーザー名
API キー	ステップ 6 で取得したクライアント ID
秘密鍵	ステップ 6.1 で生成した private_key.pem の内容

セキュリティ推奨:

• 安全なファイル転送や暗号化されたメールを使用
• 全資格情報を一つのメッセージで送信しない
• セキュアな資格情報共有サービスの利用を検討
• 送信後は一時コピーを削除

SuccessFactors で必要な権限のまとめ

mindzie 統合に必要な権限は以下の通りです：

最小必要権限

• OData API への管理者アクセス
• Employee Central OData API（Employee Central データ用）
• 従業員データ - 表示
• 雇用詳細 - 表示

用途による推奨追加権限

• 職務情報 - 表示
• 組織データ - 表示
• 個人情報 - 表示
• 報酬情報 - 表示
• 勤怠管理 OData API
• 報酬 OData API

接続テスト（任意）

SAP Business Accelerator Hub を利用して API 設定を検証できます：

1. SAP Business Accelerator Hub にアクセス
2. 「SAP SuccessFactors」API を検索
3. 「Try Out」機能を使い資格情報でログイン
4. 会社情報エンティティを取得する簡単なクエリーを試す

cURL を使った例（単純化した例です）：

# OAuth フローは実際には複雑です。例示のみ
curl -X GET "https://[your-api-server]/odata/v2/User?$top=1" \
  -H "Authorization: Bearer [your-oauth-token]" \
  -H "Accept: application/json"

ファイアウォール設定

発信アクセスが必要

mindzie サーバーから SuccessFactors データセンターへの HTTPS 発信アクセスが必要です：

ポート	プロトコル	送信先	用途
443	HTTPS	ステップ 1 の API サーバー URL	OData API 呼び出し

受信ポートは不要

mindzie 統合は完全に mindzie から SuccessFactors への発信のみです。ネットワーク側の受信ファイアウォール設定は不要です。

IP ホワイトリスト設定（任意）

セキュリティ強化のため mindzie の IP アドレスに対して API アクセスを制限可能です：

1. mindzie サポートに現在の IP アドレスを問い合わせ
2. SuccessFactors 管理センターで IP 制限を設定（サポートされている場合）
3. またはネットワークファイアウォールで mindzie IP アドレスからのみ SuccessFactors へアクセス許可設定

アクセス権限の取り消し

mindzie 統合を無効化する場合：

即時取り消し

1. 管理センター -> OAuth2 クライアントアプリケーション管理 に移動
2. mindzie アプリケーションを探す
3. 取り消し（Revoke） または 無効化（Disable） をクリックして OAuth 資格情報を無効化

完全削除

1. OAuth アプリケーションの取り消し（上記）
2. ステップ 3 で作成した技術 API ユーザーの削除または無効化
3. ステップ 5 の権限ロールの削除
4. ステップ 4 の権限グループの削除

トラブルシューティング

OAuth 認証エラー

「Invalid client credentials」

• API キー（クライアント ID）が正確か確認
• OAuth アプリケーションが取り消しや無効化されていないか確認
• X.509 証明書の有効期限を確認

「SAML assertion failed」

• 秘密鍵が SuccessFactors に登録された証明書と一致しているか確認
• 技術ユーザー ID が正しくかつ有効であるか確認
• Company ID の正確性を確認

権限拒否エラー

「Insufficient privileges」

• 技術ユーザーが正しい権限グループに割当されているか確認
• 権限ロールに必要な API 権限が有効か確認
• OData API への管理者アクセスが付与されているか確認

「Entity not accessible」

• 対象エンティティに追加の権限が必要な場合あり
• RBP 設定で該当エンティティの権限確認
• SAP ドキュメントでエンティティ固有の権限を確認

証明書関連の問題

「Certificate expired」

• 新しい X.509 証明書を生成
• OAuth アプリケーションに更新証明書を登録
• 新しい秘密鍵を mindzie に提供

「Certificate not trusted」

• 自己署名証明書の場合は正しくアップロードされているか確認
• 企業証明書の場合は証明書チェーンを検証

API レート制限

SAP SuccessFactors は API レート制限を課しています。制限に達した場合：

• mindzie は適切なスロットリングを実装
• SAP サポートに増枠依頼を検討
• クエリーレベルでのデータフィルタリングで呼び出し回数削減を検討

接続タイムアウト

「Connection timed out」

• API サーバー URL が正しいか確認
• ネットワーク接続およびファイアウォールルールを確認
• SuccessFactors 側の障害状況を確認

関連情報

• SAP SuccessFactors ヘルプポータル: help.sap.com/successfactors
• SAP Business Accelerator Hub: api.sap.com
• SuccessFactors API リファレンス: SAP SuccessFactors OData API

---

参考文献・情報源

本ドキュメントは以下を参照して作成されています：

公式 SAP ドキュメント

• SAP SuccessFactors プラットフォーム ドキュメント - 公式プラットフォームドキュメント
• SAP SuccessFactors API リファレンス - OData API ドキュメント
• SAP SuccessFactors データセンター情報 - データセンター関連情報
• OAuth 2.0 SAML ベアラーアサーション - OAuth 認証ガイド

SAP コミュニティリソース

• SAP コミュニティ - SuccessFactors - コミュニティディスカッションやベストプラクティス
• SAP Business Accelerator Hub - API テストおよびドキュメント閲覧サイト