共用方式為

Microsoft Entra 佈建如何與 SAP SuccessFactors 整合

  • 發行項

整合 Microsoft Entra 使用者佈建服務與 SAP SuccessFactors 員工中心，以管理使用者的身分識別生命週期。 Microsoft Entra ID 可提供三種預建整合方式：

本文說明整合的運作方式，以及如何針對不同的 HR 案例自訂佈建行為。

Microsoft Entra 也支援 SuccessFactors 的單一登入。 如需詳細資訊，請參閱 Microsoft Entra 單一登入 (SSO) 與 SuccessFactors 整合 (部分機器翻譯)。

建立連線

Microsoft Entra 佈建服務會使用基本驗證來連線至員工中心 OData API 端點。 設定 SuccessFactors 佈建應用程式時，請使用 [管理員認證] 區段中的 [租用戶 URL] 參數來設定 API 資料中心 URL。

若要進一步保護 Microsoft Entra 佈建服務與 SuccessFactors 之間的連線，請在 SuccessFactors IP 允許清單中新增 Microsoft Entra IP 範圍：

  1. 下載 Azure 公用雲端的最新 IP 範圍。
  2. 開啟檔案並搜尋標籤 AzureActiveDirectory。
  3. 複製元素 addressPrefixes 內所列的所有 IP 位址範圍，並使用該範圍建置您的 IP 位址限制清單。
  4. 將 CIDR 值轉譯為 IP 範圍。
  5. 登入 SuccessFactors 管理入口網站，以將 IP 範圍新增至允許清單。 請參閱 SAP 支援附註 2253200。 現在，您可以在此工具中輸入 IP 範圍。

支援的實體

對於 SuccessFactors 中的每個使用者，Microsoft Entra 佈建服務都會擷取下列實體。 每個實體都可使用 [擷取規則] 資料行所列的 OData API $expand 查詢參數來展開。 有些實體會預設為展開，有些實體則在對應中有特定屬性時才會展開。

# SuccessFactors 實體 OData 節點 擷取規則
1 PerPerson *root node* 一律
2 PerPersonal personalInfoNav 永遠
3 PerPhone phoneNav 永遠
4 PerEmail emailNav 永遠
5 EmpEmployment employmentNav 永遠
6 User employmentNav/userNav 永遠
7 EmpJob employmentNav/jobInfoNav 永遠
8 EmpEmploymentTermination activeEmploymentsCount 永遠
9 User's manager employmentNav/userNav/manager/empInfo 永遠
10 FOCompany employmentNav/jobInfoNav/companyNav 只有在 company 或 companyId 屬性已對應時
11 FODepartment employmentNav/jobInfoNav/departmentNav 只有在 department 或 departmentId 屬性已對應時
12 FOBusinessUnit employmentNav/jobInfoNav/businessUnitNav 只有在 businessUnit 或 businessUnitId 屬性已對應時
13 FOCostCenter employmentNav/jobInfoNav/costCenterNav 只有在 costCenter 或 costCenterId 屬性已對應時
14 FODivision employmentNav/jobInfoNav/divisionNav 只有在 division 或 divisionId 屬性已對應時
15 FOJobCode employmentNav/jobInfoNav/jobCodeNav 只有在 jobCode 或 jobCodeId 屬性已對應時
16 FOPayGrade employmentNav/jobInfoNav/payGradeNav 只有在 payGrade 屬性已對應時
17 FOLocation employmentNav/jobInfoNav/locationNav 只有在 location 屬性已對應時
18 FOCorporateAddressDEFLT employmentNav/jobInfoNav/addressNavDEFLT 如果對應包含下列其中一個屬性：officeLocationAddress, officeLocationCity, officeLocationZipCode
19 FOEventReason employmentNav/jobInfoNav/eventReasonNav 只有在 eventReason 屬性已對應時
20 EmpGlobalAssignment employmentNav/empGlobalAssignmentNav 只有在 assignmentType 已對應時
21 EmploymentType Picklist employmentNav/jobInfoNav/employmentTypeNav 只有在 employmentType 已對應時
22 EmployeeClass Picklist employmentNav/jobInfoNav/employeeClassNav 只有在 employeeClass 已對應時
23 EmplStatus Picklist employmentNav/jobInfoNav/emplStatusNav 只有在 emplStatus 已對應時
24 AssignmentType Picklist employmentNav/empGlobalAssignmentNav/assignmentTypeNav 只有在 assignmentType 已對應時
25 Position employmentNav/jobInfoNav/positionNav 只有在 positioNav 已對應時
26 Manager User employmentNav/jobInfoNav/managerUserNav 只有在 managerUserNav 已對應時

完整同步處理的運作方式

根據屬性對應，在完整同步處理期間，Microsoft Entra 佈建服務會傳送下列 "GET" OData API 查詢，以擷取所有作用中和已解雇員工的有效資料。

參數 描述
OData API 主機 將 https 附加至租用戶 URL。 範例: https://api4.successfactors.com
OData API 端點 /odata/v2/PerPerson
OData $format 查詢參數 json
OData $filter 查詢參數 (personEmpTerminationInfoNav/activeEmploymentsCount ne null) and (lastModifiedDateTime le <CurrentExecutionTime>)
OData $expand 查詢參數 此參數值取決於對應的屬性。 範例: employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav
OData customPageSize 查詢參數 100

注意

在完整初始同步處理期間，將會從 SAP SuccessFactors 擷取作用中和已解雇的員工角色。

對於每個 SuccessFactors 使用者，佈建服務會使用對應中定義的相符屬性，尋找目標 (Microsoft Entra ID/內部部署 Active Directory) 中的帳戶。 例如：如果 personIdExternal 對應至 employeeId，並設定為相符的屬性，則佈建服務會使用 personIdExternal 值來搜尋具有 employeeId 篩選條件的使用者。 如果找到相符的使用者，則會更新目標屬性。 如果找不到相符項目，則會在目標中建立新項目。

若要驗證 OData API 端點針對特定 personIdExternal 傳回的資料，請使用您的 API 資料中心伺服器 URL 更新 API 查詢中的 SuccessFactorsAPIEndpoint，並使用 cURL 或 Graph 總管之類的工具來叫用查詢。 如果 "in" 篩選無法運作，則可嘗試 "eq" 篩選。

https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&
$filter=(personIdExternal in '[personIdExternalValue]')&
$expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,
phoneNav,phoneNav/phoneTypeNav,emailNav,employmentNav/jobInfoNav/businessUnitNav,employmentNav/jobInfoNav/companyNav,
employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/costCenterNav,
employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/jobCodeNav,
employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/payGradeNav,
employmentNav/empGlobalAssignmentNav,employmentNav/empGlobalAssignmentNav/assignmentTypeNav,employmentNav/jobInfoNav/emplStatusNav,
employmentNav/jobInfoNav/employmentTypeNav,employmentNav/jobInfoNav/employeeClassNav,employmentNav/jobInfoNav/eventReasonNav

增量同步處理的運作方式

完成完整同步處理之後，Microsoft Entra 佈建服務會保有 LastExecutionTimestamp，並將其用於建立差異查詢，以擷取增量變更。 每個 SuccessFactors 實體中的時間戳記屬性 (例如 lastModifiedDateTime、startDate、endDate 和 latestTerminationDate) 都會進行評估，以查看變更是否落在 LastExecutionTimestamp 和 CurrentExecutionTime 之間。 如果是，則項目變更會被視為有效並進行同步處理。

以下是 Microsoft Entra ID 用來查詢 SuccessFactors 以取得累加變更的 OData API 要求範本。 您可以更新變數 SuccessFactorsAPIEndpoint、LastExecutionTimestamp 和 CurrentExecutionTime。在要求範本中，使用 cURL 或 Graph 總管之類的工具來檢查傳回什麼資料。 或者，您也可以啟用 OData API 稽核記錄，從 SuccessFactors 擷取實際的要求酬載。

https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson/$count?$format=json&$filter=(personEmpTerminationInfoNav/activeEmploymentsCount ne null) and
((lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') or
(personalInfoNav/startDate ge datetimeoffset'<LastExecutionTimestamp>' and personalInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>') or
((personalInfoNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and personalInfoNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') and (personalInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>' and (personalInfoNav/endDate ge datetimeoffset'<CurrentExecutionTime>' or  personalInfoNav/endDate eq null))) or
(employmentNav/startDate ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/startDate le datetimeoffset'<CurrentExecutionTime>') or
((employmentNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') and (employmentNav/startDate le datetimeoffset'<CurrentExecutionTime>' and (employmentNav/endDate ge datetimeoffset'<CurrentExecutionTime>' or employmentNav/endDate eq null))) 
(employmentNav/jobInfoNav/startDate ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/jobInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>') or
((employmentNav/jobInfoNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/jobInfoNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') and (employmentNav/jobInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>' and (employmentNav/jobInfoNav/endDate ge datetimeoffset'<CurrentExecutionTime>' or employmentNav/jobInfoNav/endDate eq null))) or
(phoneNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and phoneNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') or
(emailNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and emailNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') or
(personEmpTerminationInfoNav/latestTerminationDate ge datetimeoffset'<previousDayDateStartTime24hrs>' and personEmpTerminationInfoNav/latestTerminationDate le datetimeoffset'<previousDayDateTime24hrs>') or
(employmentNav/userNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/userNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>'))
&$expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/userNav/manager/empInfo,employmentNav/jobInfoNav/companyNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/locationNav/addressNavDEFLT/stateNav&customPageSize=100

預先僱用處理的運作方式

本節說明 SAP SuccessFactors 連接器如何處理預先雇用記錄 (有未來雇用日期/開始日期的員工)。 假設 SuccessFactors 員工中心中有 employeeId「1234」的預先雇用員工，開始日期為 2023 年 6 月 1 日。 讓我們進一步假設此預先雇用記錄是先在員工中心或 2023 年 5 月 15 日上線課程模組中建立的。 佈建服務第一次在 2023 年 5 月 15 日發現此記錄時 (無論是完整同步或增量同步的一部分)，此記錄仍處於預先雇用狀態。 因此，SuccessFactors 不會將與使用者相關聯的所有屬性 (例如：userNav/使用者名稱) 傳送給佈建服務。 僅提供最低限度的使用者相關資料，例如companyName、personIdExternal、firstname、lastname 和 startDate。 若要順利處理預先雇用，必須符合下列必要條件：

  1. 必須將 personIdExternal 屬性設定為主要比對識別碼 (聯結屬性)。 若將不同的屬性 (例如：userName) 設定為聯結屬性，則佈建服務將無法擷取預先雇用資訊。
  2. startDate 屬性必須可用，且其 JSONPath 必須設定為 $.employmentNav.results[0].startDate 或 $.employmentNav.results[-1:].startDate。
  3. 在員工中心中，預先雇用的記錄狀態必須為以下其一：「作用中」(t)、「非作用中」(f) 或 'active_external_suite' (e)。 如需這些狀態的詳細資訊，請參閱 SAP 支援附註 2736579。

注意

對於沒有組織歷程記錄的預先僱用人員，[0] 和 [-1:] 索引都適用於 startDate。 對於重新雇用或轉換的預先僱用人員，我們無法確實掌握順序，這可能會導致系統在實際開始日期已開始處理某些重新僱用/轉換的員工。 這是連接器的已知限制。

在完整同步處理、增量同步或隨選佈建期間，佈建服務遇到預先雇用記錄時，會將下列 OData 查詢傳送至 SuccessFactors，並將「asOfDate」篩選條件設定為使用者的 startDate (例如 OfDate=2023-06-01)。

https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&$
filter=(personIdExternal in '1234' and employmentNav/userNav/status in 't','f','e')&asOfDate=2023-06-01&$
expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/userNav/manager/empInfo,employmentNav/jobInfoNav/companyNav,employmentNav/jobInfoNav/costCenterNav,employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/

若發現預先雇用處理的問題，您可以使用上述 OData 要求格式來查詢 SuccessFactors 執行個體，以取代 API 端點，並使用 personIdExternal 和 asOfDate 對應至測試案例的值進行篩選。

讀取屬性資料

Microsoft Entra 佈建服務查詢 SuccessFactors 時，會擷取 JSON 結果集。 JSON 結果集包含許多儲存在員工中心的屬性。 根據預設，佈建結構描述會設定為僅擷取這些屬性的子集。

若要取得更多屬性，請遵循下列步驟：

  1. 瀏覽至 [企業應用程式] ->[SuccessFactors 應用程式] ->[佈建] ->[編輯佈建] ->[屬性對應頁面]。

  2. 向下捲動，然後按一下 [顯示進階選項]。

  3. 按一下 [編輯 SuccessFactors 的屬性清單]。

    注意

    如果 [SuccessFactors 的編輯屬性清單] 選項未顯示在 Microsoft Entra 系統管理中心，請使用 URL https://portal.azure.com/?Microsoft_AAD_IAM_forceSchemaEditorEnabled=true 來存取頁面。

  4. 此檢視中的 [API 運算式] 資料行會顯示連接器所使用的 JSONPath 運算式。

    API 運算式

  5. 您可以編輯現有的 JSONPath 值，或使用有效的 JSONPath 運算式將新的屬性新增至結構描述。

下一節將提供編輯 JSONPath 值的常見案例清單。

處理不同的 HR 案例

JSONPath 是 JSON 的查詢語言，如同用於 XML 的 XPath。 就像 XPath 一樣，JSONPath 可讓您從 JSON 承載中擷取和篩選資料。

您可以使用 JSONPath 轉換來自訂 Microsoft Entra 佈建應用程式的行為，以擷取自訂屬性和處理案例，例如再雇用、員工轉換和全域指派。

本節說明如何針對下列 HR 案例自訂佈建應用程式：

擷取更多屬性

預設 Microsoft Entra SuccessFactors 佈建應用程式結構描述隨附超過 90 個預先定義的屬性。 若要將更多 SuccessFactors 屬性新增至佈建結構描述，請按照下列步驟操作：

  1. 使用 OData 查詢，從員工中心擷取有效測試使用者的資料。

     https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&
 $filter=(personIdExternal in '[personIdExternalValue]')&
 $expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,
 phoneNav,phoneNav/phoneTypeNav,emailNav,employmentNav/jobInfoNav/businessUnitNav,employmentNav/jobInfoNav/companyNav,
 employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/costCenterNav,
 employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/jobCodeNav,
 employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/payGradeNav,
 employmentNav/empGlobalAssignmentNav,employmentNav/empGlobalAssignmentNav/assignmentTypeNav,employmentNav/jobInfoNav/emplStatusNav,
 employmentNav/jobInfoNav/employmentTypeNav,employmentNav/jobInfoNav/employeeClassNav,employmentNav/jobInfoNav/eventReasonNav

  2. 確認與屬性相關聯的員工中心實體

    • 如果屬性是 EmpEmployment 實體的一部分，請在 employmentNav 節點 底下尋找屬性。
    • 如果屬性是 User 實體的一部分，請在 employmentNav/userNav 節點底下尋找屬性。
    • 如果屬性是 EmpJob 實體的一部分，請在 employmentNav/jobInfoNav 節點底下尋找屬性。

  3. 建構與屬性相關聯的 JSON 路徑，並將這個新屬性新增至 SuccessFactors 屬性清單。

    • 範例 1：假設您想要新增屬性 okToRehire (這是 employmentNav 實體的一部分)，然後使用 JSONPath $.employmentNav.results[0].okToRehire
    • 範例 2：假設您想要新增屬性 timeZone (這是 userNav 實體的一部分)，然後使用 JSONPath $.employmentNav.results[0].userNav.timeZone
    • 範例 3：假設您想要新增屬性 flsaStatus (這是 jobInfoNav 實體的一部分)，然後使用 JSONPath $.employmentNav.results[0].jobInfoNav.results[0].flsaStatus

  4. 儲存結構描述。

  5. 重新啟動佈建。

擷取自訂屬性

根據預設，下列自訂屬性會預先定義於 Microsoft Entra SuccessFactors 佈建應用程式中：

  • custom01-custom15，來自使用者 (userNav) 實體
  • customString1-customString15，來自名為 empNavCustomString1-empNavCustomString15 的 EmpEmployment (employmentNav) 實體
  • customString1-customString15，來自名為 empJobNavCustomString1-empNavJobCustomString15 的 EmpJobInfo (jobInfoNav) 實體

假設在您的員工中心執行個體中，EmpJobInfo 中的 customString35 屬性儲存了位置描述。 您想要將此值傳送至 Active Directory physicalDeliveryOfficeName 屬性。 若要設定此案例的屬性對應，請按照下列步驟操作：

  1. 編輯 SuccessFactors 屬性清單，以新增名為 empJobNavCustomString35 的新屬性。
  2. 將此屬性的 JSONPath API 運算式設定為：$.employmentNav.results[0].jobInfoNav.results[0].customString35
  3. 儲存並重新載入 Microsoft Entra 系統管理中心的對應變更。
  4. 在屬性對應刀鋒視窗中，將 empJobNavCustomString35 對應至 physicalDeliveryOfficeName。
  5. 儲存對應。

擴充此案例：

  • 如果您想要從 User 實體對應 custom35 屬性，請使用 JSONPath $.employmentNav.results[0].userNav.custom35
  • 如果您想要從 EmpEmployment 實體對應 customString35 屬性，請使用 JSONPath $.employmentNav.results[0].customString35

將雇用狀態對應至帳戶狀態

根據預設，Microsoft Entra SuccessFactors 連接器會使用 PersonEmpTerminationInfo 物件的 activeEmploymentsCount 欄位來設定帳戶狀態。 您可能會遇到下列其中一個屬性的問題。

  1. 有一個已知問題，連接器可能會在工作的最後一天，停用已終止工作者的帳戶。
  2. 如果 PersonEmpTerminationInfo 物件設定為 Null，則在終止期間，AD 帳戶將停用無法運作，因為佈建引擎會篩選掉 personEmpTerminationInfoNav 物件設定為 Null 的記錄。

若遇到任何此類問題，或偏好將雇用狀態對應至帳戶狀態，則可更新對應以展開 emplStatus 欄位，並使用欄位 emplStatus.externalCode 中存在的雇用狀態碼。 根據 SAP 支援注意事項2505526，以下是您可以在佈建應用程式時擷取的雇用狀態碼清單。

  • A = 在職
  • D = 補休
  • U = 無薪假
  • P = 有薪假
  • S = 停職
  • F = 留職停薪
  • O = 辭職
  • R = 退休
  • T = 解雇

按照這些步驟來更新您的對應以擷取這些代碼。

  1. 開啟 SuccessFactors 佈建應用程式的屬性對應刀鋒視窗。

  2. 在 [顯示進階選項] 底下，按一下 [編輯 SuccessFactors 屬性清單]。

  3. 尋找 emplStatus 屬性，並將 JSONPath 更新為 $.employmentNav.results[0].jobInfoNav.results[0].emplStatusNav.externalCode。 更新會讓連接器擷取資料表中的雇用狀態碼。

  4. 儲存變更。

  5. 在 [屬性對應] 刀鋒視窗中，更新帳戶狀態旗標的運算式對應。

    佈建作業 帳戶狀態屬性 對應運算式
    SuccessFactors 到 Active Directory 使用者佈建 accountDisabled Switch([emplStatus], "True", "A", "False", "U", "False", "P", "False")
    SuccessFactors 至 Microsoft Entra 使用者佈建 accountEnabled Switch([emplStatus], "False", "A", "True", "U", "True", "P", "True")

  6. 儲存變更。

  7. 使用隨選佈建測試設定。

  8. 在確認同步如預期般運作之後，請重新啟動佈建作業。

處理員工轉換和重新雇用案例

關於員工轉換案例：員工轉換是指將現有全職員工轉換成約聘員工，或約聘員工轉換成全職員工。 在此案例中，員工中心會將新的 EmpEmployment 實體與相同 Person 實體的新 User 實體一併新增。 在先前的 EmpEmployment 實體下內嵌的 User 實體會設定為 Null。

關於重新雇用案例：在 SuccessFactors 中，有兩個選項可處理重新雇用員工：

  • 選項 1：在員工中心建立新的人員設定檔
  • 選項 2：在員工中心重複使用現有的個人設定檔

如果您的 HR 程序使用選項 1，則不需要變更佈建結構描述。 如果您的 HR 程序使用選項 2，員工中心會將新的 EmpEmployment 實體與相同 Person 實體的新 User 實體一併新增。

處理好這兩個案例後，系統即可在轉換或重新雇用時顯示新的員工資料。 使用所列的步驟大量更新佈建應用程式結構描述：

  1. 開啟 SuccessFactors 佈建應用程式的屬性對應刀鋒視窗。

  2. 向下捲動，然後按一下 [顯示進階選項]。

  3. 按一下 [在此處檢閱結構描述] 連結，以開啟結構描述編輯器。

    螢幕擷取畫面：用於開啟結構描述編輯器的 [在此處檢閱結構描述] 連結。

  4. 按一下 [下載] 連結，以在編輯之前儲存結構描述的複本。

    螢幕擷取畫面：結構描述編輯器，已選取 [下載] 以儲存結構描述的複本。

  5. 在結構描述編輯器中，按 Ctrl-H 鍵以開啟 [尋找/取代] 控制項。

  6. 在 [尋找] 文字方塊中，複製並貼上值 $.employmentNav.results[0]

  7. 在 [取代] 文字方塊中，複製並貼上值 $.employmentNav.results[-1:]。 此 JSONPath 運算式會傳回最新的 EmpEmployment 記錄。

    find-replace-conversion

  8. 按一下 [全部取代] 選項以更新結構描述。

  9. 儲存結構描述。

  10. 上述程序會更新所有的 JSONPath 運算式，如下所示：

    • 舊的 JSONPath：$.employmentNav.results[0].jobInfoNav.results[0].departmentNav.name_localized
    • 新的 JSONPath：$.employmentNav.results[-1:].jobInfoNav.results[0].departmentNav.name_localized

  11. 使用隨選佈建測試設定。

  12. 在確認同步如預期般運作之後，請重新啟動佈建作業。

注意

僅在 SAP SuccessFactors 以遞增順序傳回雇用物件時，上述方法才能運作，其中最新的雇用記錄一律是 employmentNav 結果陣列中的最後一筆記錄。 SuccessFactors 不保證傳回多筆雇用記錄的順序。 如果您的 SuccessFactors 執行個體具有多筆對應到員工的雇用記錄，而且您一律想要擷取與作用中雇用記錄相關聯的屬性，請使用下一節所述的步驟。

擷取目前的作用中雇用記錄

使用 $.employmentNav.results[0] 或 $.employmentNav.results[-1:] 的 JSONPath 根目錄來擷取雇用記錄，在大部分情況下可以運作，並讓設定保持簡單。 不過，根據 SuccessFactors 執行個體的設定方式，可能需要更新此設定，以確保連接器一律會擷取最新的作用中雇用記錄。

本節描述如何更新 JSONPath 設定，以絕對擷取使用者的目前作用中雇用記錄。 此設定也會處理員工轉換和重新雇用案例。

  1. 開啟 SuccessFactors 佈建應用程式的屬性對應刀鋒視窗。

  2. 向下捲動，然後按一下 [顯示進階選項]。

  3. 按一下 [在此處檢閱結構描述] 連結，以開啟結構描述編輯器。

  4. 按一下 [下載] 連結，以在編輯之前儲存結構描述的複本。

  5. 在結構描述編輯器中，按 Ctrl-H 鍵以開啟 [尋找/取代] 控制項。

  6. 執行下列尋找取代作業。 執行尋找-取代作業時，請確定沒有前置或尾端空格。 若使用 [-1:] 索引而非 [0]，請據以更新 [要尋找的字串] 欄位。

    要尋找的字串 要用於取代的字串 用途
    $.employmentNav.results[0].jobInfoNav.results[0].emplStatus $.employmentNav..jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P' )].emplStatusNav.externalCode 透過這個尋找-取代，我們會新增擴充 emplStatusNav OData 物件的能力。
    $.employmentNav.results[0].jobInfoNav.results[0] $.employmentNav..jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P')] 透過這個尋找-取代，我們指示連接器一律擷取與作用中 SuccessFactors EmpJobInfo 記錄相關聯的屬性。 將會忽略與 SuccessFactors 中已終止/非作用中記錄相關聯的屬性。
    $.employmentNav.results[0] $.employmentNav..results[?(@.jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P')])] 透過這個尋找-取代，我們指示連接器一律擷取與作用中 SuccessFactors Employment 記錄相關聯的屬性。 將會忽略與 SuccessFactors 中已終止/非作用中記錄相關聯的屬性。

  7. 儲存結構描述。

  8. 上述流程會更新所有的 JSONPath 運算式。

  9. 若要讓預先雇用處理能夠運作，與 startDate 屬性相關聯的 JSONPath 必須使用 [0] 或 [-1:] 索引。 在 [顯示進階選項] 底下，按一下 [編輯 SuccessFactors 屬性清單]。 尋找 startDate 屬性，並將其設定為 $.employmentNav.results[-1:].startDate 值

  10. 儲存結構描述。

  11. 若要確保如預期般處理終止，您可以在屬性對應區段中使用下列其中一個設定。

    佈建作業 帳戶狀態屬性 要在帳戶狀態以 "activeEmploymentsCount" 為基礎時使用的運算式 要在帳戶狀態以 "emplStatus" 值為基礎時使用的運算式
    SuccessFactors 到 Active Directory 使用者佈建 accountDisabled Switch([activeEmploymentsCount], "False", "0", "True") Switch([emplStatus], "True", "A", "False", "U", "False", "P", "False")
    SuccessFactors 至 Microsoft Entra 使用者佈建 accountEnabled Switch([activeEmploymentsCount], "True", "0", "False") Switch([emplStatus], "False", "A", "True", "U", "True", "P", "True")

  12. 儲存您的變更。 1.

  13. 使用隨選佈建測試設定。

  14. 在確認同步如預期般運作之後，請重新啟動佈建作業。

處理全域指派案例

對員工中心內的使用者進行全域指派的處理時，SuccessFactors 會新增一個新的 EmpEmployment 實體，並將 assignmentClass 設定為 "GA"。 此外也會建立新的 User 實體。 因此，使用者此時會有：

  • 一個 EmpEmployment + User 實體，對應於將 assignmentClass 設定為 "ST" 的起始指派，以及
  • 另一個 EmpEmployment + User 實體，對應於將 assignmentClass 設定為 "GA" 的全域指派

若要擷取屬於標準指派和全域指派使用者設定檔的屬性，請按照下列步驟操作：

  1. 開啟 SuccessFactors 佈建應用程式的屬性對應刀鋒視窗。

  2. 向下捲動，然後按一下 [顯示進階選項]。

  3. 按一下 [在此處檢閱結構描述] 連結，以開啟結構描述編輯器。

  4. 按一下 [下載] 連結，以在編輯之前儲存結構描述的複本。

  5. 在結構描述編輯器中，按 Ctrl-H 鍵以開啟 [尋找/取代] 控制項。

  6. 在 [尋找] 文字方塊中，複製並貼上值 $.employmentNav.results[0]

  7. 在 [取代] 文字方塊中，複製並貼上值 $.employmentNav.results[?(@.assignmentClass == 'ST')]。 請注意，== 運算子兩側需加上空格，如此才能成功處理 JSONPath 運算式。

  8. 按一下 [全部取代] 選項以更新結構描述。

  9. 儲存結構描述。

  10. 上述程序會更新所有的 JSONPath 運算式，如下所示：

    • 舊的 JSONPath：$.employmentNav.results[0].jobInfoNav.results[0].departmentNav.name_localized
    • 新的 JSONPath：$.employmentNav.results[?(@.assignmentClass == 'ST')].jobInfoNav.results[0].departmentNav.name_localized

  11. 重新載入應用程式的屬性對應刀鋒視窗。

  12. 向下捲動，然後按一下 [顯示進階選項]。

  13. 按一下 [編輯 SuccessFactors 的屬性清單]。

  14. 新增屬性以擷取全域指派資料。 例如：如果您想要擷取與全域指派設定檔相關聯的部門名稱，您可以將 JSONPath 運算式設定為 $.employmentNav.results[?(@.assignmentClass == 'GA')].jobInfoNav.results[0].departmentNav.name_localized 的屬性 globalAssignmentDepartment。

  15. 您現在可以將兩個部門值傳送至 Active Directory 屬性，或選擇性地使用運算式對應來傳送值。 範例：運算式會將 AD department 屬性的值設定為 globalAssignmentDepartment (如果有的話)，否則，會將值設定為與標準指派相關聯的 department。

    • IIF(IsPresent([globalAssignmentDepartment]),[globalAssignmentDepartment],[department])

  16. 儲存對應。

  17. 使用隨選佈建測試設定。

  18. 在確認同步如預期般運作之後，請重新啟動佈建作業。

處理並行作業案例

當員工中心內的使用者具有並行/多個作業時，會有兩個 EmpEmployment 和 User 實體將 assignmentClass 設定為 "ST"。 若要擷取屬於這兩個作業的屬性，請按照下列步驟操作：

  1. 開啟 SuccessFactors 佈建應用程式的屬性對應刀鋒視窗。
  2. 向下捲動，然後按一下 [顯示進階選項]。
  3. 按一下 [編輯 SuccessFactors 的屬性清單]。
  4. 假設您想要提取與作業 1 和作業 2 相關聯的部門。 預先定義的屬性 department 已為第一項作業擷取部門的值。 您可以定義名為 secondJobDepartment 的新屬性，並將 JSONPath 運算式設定為 $.employmentNav.results[1].jobInfoNav.results[0].departmentNav.name_localized
  5. 您現在可以將兩個部門值傳送至 Active Directory 屬性，或選擇性地使用運算式對應來傳送值。
  6. 儲存對應。
  7. 使用隨選佈建測試設定。
  8. 在確認同步如預期般運作之後，請重新啟動佈建作業。

擷取位置詳細資料

SuccessFactors 連接器支援位置物件的展開。 若要展開並擷取特定語言的位置物件屬性 (例如作業層級或位置名稱)，您可以使用 JSONPath 運算式，如下所示。

屬性名稱 JSONPath 運算式
positionJobLevel $.employmentNav.results[0].jobInfoNav.results[0].positionNav.jobLevel
positionNameFR $.employmentNav.results[0].jobInfoNav.results[0].positionNav.externalName_fr_FR
positionNameDE $.employmentNav.results[0].jobInfoNav.results[0].positionNav.externalName_de_DE

在 Onboarding 模組中佈建使用者

從 SAP SuccessFactors 到內部部署 Active Directory 和 Microsoft Entra ID 的輸入使用者佈建，現在支援預先佈建 SAP SuccessFactors Onboarding 2.0 模組中的預先雇用。 Microsoft Entra 佈建服務遇到新的雇用設定檔開始日期是在未來時，會查詢 SAP SuccessFactors，以取得具有下列其中一個狀態碼的新進員工：active、inactive、active_external_suite。 狀態碼 active_external_suite 對應於出現在 SAP SuccessFactors Onboarding 2.0 模組中的預先雇用。 如需這些狀態碼的說明，請參閱 SAP 支援附註 2736579。

佈建服務的預設行為，是在 Onboarding 模組中處理預先雇用。

若要在 Onboarding 模組中排除預先雇用的處理，請更新佈建作業設定，如下所示：

  1. 開啟 SuccessFactors 佈建應用程式的屬性對應刀鋒視窗。
  2. 在 [顯示進階選項] 底下編輯 SuccessFactors 屬性清單，以新增名為 userStatus 的新屬性。
  3. 將此屬性的 JSONPath API 運算式設定為：$.employmentNav.results[0].userNav.status
  4. 儲存結構描述，以返回屬性對應刀鋒視窗。
  5. 編輯來源物件範圍以套用範圍篩選條件 userStatus NOT EQUALS
  6. 儲存對應，並使用隨需佈建驗證範圍篩選條件是否可運作。

在 SuccessFactors 中啟用 OData API 稽核記錄

Microsoft Entra SuccessFactors 連接器會使用 SuccessFactors OData API，來擷取變更並佈建使用者。 若發現佈建服務有問題，並想要確認已從 SuccessFactors 擷取哪些資料，請在 SuccessFactors 中啟用 OData API 稽核記錄。 從這些稽核記錄中擷取 Microsoft Entra ID 所傳送的要求酬載。 若要進行疑難排解，您可以在 cURL 或 Graph 總管之類的工具中複製此要求酬載、將其設定為使用連接器所使用的相同 API 使用者，並查看其是否從 SuccessFactors 傳回所需的變更。

回寫案例

本節說明不同的回寫案例。 文中將根據在 SuccessFactors 中設定電子郵件和電話號碼的方式，提供建議的設定方法。

電話和電子郵件回寫的支援案例

# 案例需求 電子郵件主要
旗標值		 商務電話
主要旗標值		 行動電話
主要旗標值		 商務電話
對應		 行動電話
對應
1 * 僅將公司電子郵件設定為主要。
* 不設定電話號碼。		 true true false [未設定] [未設定]
2 * 在 SuccessFactors 中，公司電子郵件和公司電話是主要連絡方式
* 一律將 Microsoft Entra 電話號碼傳送至公司電話，並將行動電話傳送至手機。		 true true false telephoneNumber 行動
3 * 在 SuccessFactors 中，公司電子郵件和手機是主要連絡方式
* 一律將 Microsoft Entra 電話號碼傳送至公司電話，並將行動電話傳送至手機		 true false true telephoneNumber 行動
4 * SuccessFactors 公司電子郵件是主要連絡方式。
* 在 Microsoft Entra ID 中，請檢查工作電話號碼是否存在，如果有，則檢查行動電話號碼是否也存在。 只有在行動電話號碼不存在時，才會將公司電話號碼標示為主要電話號碼。		 true 使用運算式對應：IIF(IsPresent([telephoneNumber]), IIF(IsPresent([mobile]),"false", "true"), "false") 使用運算式對應：IIF(IsPresent([mobile]),"false", "true") telephoneNumber 行動
5 * 在 SuccessFactors 中，公司電子郵件和公司電話是主要連絡方式。
* 在 Microsoft Entra ID 中，如果行動電話可供使用，則將其設定為公司電話，若沒有則使用 telephoneNumber。		 true true false IIF(IsPresent([mobile]), [mobile], [telephoneNumber]) [未設定]
  • 如果在回寫屬性對應中沒有電話號碼的對應，則回寫中只會包含電子郵件。
  • 新員工在員工中心上線期間，公司電子郵件和電話號碼可能無法使用。 如果在上線期間必須將公司電子郵件和公司電話設定為主要連絡方式，您可以在新員工建立期間設定公司電話和電子郵件的虛擬值。 經過一段時間之後，回寫應用程式會更新值。

透過 UserID 啟用回寫

SuccessFactors 回寫應用程式會使用下列邏輯來更新使用者物件屬性：

  • 第一個步驟是在變更集中尋找 userId 屬性。 如果存在，則會使用 "UserId" 進行 SuccessFactors API 呼叫。
  • 如果找不到 userId，則依預設會使用 personIdExternal 屬性值。

SuccessFactors 中的 personIdExternal 屬性值通常會符合 userId 屬性值。 不過，在再雇用和員工轉換等案例中，SuccessFactors 中的員工可能會有兩筆雇用記錄，一個作用中，一個非作用中。 在這種情況下，為了確保回寫會更新作用中的使用者設定檔，請依照描述更新 SuccessFactors 佈建應用程式的設定。 此設定可確保 userId 一律會存在於連接器可見的變更集中，並且用於 SuccessFactors API 呼叫中。

  1. 開啟 Microsoft Entra 使用者佈建應用程式的 SuccessFactors，或開啟內部部署 AD 使用者佈建應用程式的 SuccessFactors。
  2. 請確認 Microsoft Entra ID 中的 extensionAttribute[1-15] 一律會儲存每位工作者的作用中雇用記錄 userId。 記錄會將 SuccessFactors userId 屬性對應至 extensionAttribute[1-15] Microsoft Entra ID 中。

    輸入 UserID 屬性對應

  3. 如需 JSONPath 設定的指導，請參閱處理員工轉換和重新雇用案例一節，以確保作用中雇用記錄的 userId 值會傳送至 Microsoft Entra ID 中。
  4. 儲存對應。
  5. 執行佈建作業，以確保 userId 值會傳送至 Microsoft Entra ID 中。

    注意

    若目前是使用內部部署 Active Directory 使用者所佈建的 SuccessFactors，請設定 Microsoft Entra Connect，將 userId 屬性值從內部部署 Active Directory 同步處理至 Microsoft Entra ID。

  6. 在 Azure 入口網站中開啟 SuccessFactors 回寫應用程式。
  7. 將包含 userId 值的所需 extensionAttribute 對應至 SuccessFactors userId 屬性。

    回寫 UserID 屬性對應

  8. 儲存對應。
  9. 移至 [屬性對應] -> [進階] -> [檢閱結構描述]，以開啟 JSON 結構描述編輯器。
  10. 下載結構描述的複本作為備份。
  11. 在結構描述編輯器中按 Ctrl-F，並搜尋包含 userId 對應的 JSON 節點，該節點對應至來源 Microsoft Entra 屬性。
  12. 將 flowBehavior 屬性從 "FlowWhenChanged" 更新為 "FlowAlways"，如下所示。

    對應流程行為更新

  13. 儲存對應，並使用隨需佈建來測試回寫案例。

電話和電子郵件回寫不支援的案例

  • 在員工中心，個人電子郵件和個人電話在上線期間會設定為主要連絡方式。 回寫應用程式無法切換此設定，且會將公司電子郵件和公司電話設定為主要連絡方式。
  • 在員工中心，公司電話會設定為主要連絡方式。 回寫應用程式無法變更此設定，且會將行動電話設定為主要連絡方式。
  • 回寫應用程式無法讀取目前的主要旗標設定，且會使用相同的值進行寫入作業。 將一律使用屬性對應中設定的旗標值。

下一步