共用方式為

Dayforce HCM（預覽）

連接 Dayforce HCM API，透過員工參考碼取得員工個人資訊（聯絡人、地址、姓名）。 本書主要針對人力資源管理員及低程式碼開發者。 需要 Dayforce 租戶、API 憑證（基本認證）以及適當的權限。 唯讀;無效參考碼會回傳錯誤。

此連接器適用於以下產品和區域：

Service Class 區域
副駕駛工作室 進階 除下列區域外的所有 Power Automate 區域 ：
     - 美國政府 （GCC）
     - 美國政府（海灣合作委員會高中）
     - 由 21Vianet 營運的中國雲
     - 美國國防部 （DoD）
邏輯應用程式 標準 所有 Logic Apps 區域， 但下列區域除外：
     - Azure Government 區域
     - Azure 中國區域
     - 美國國防部 （DoD）
Power Apps 進階 除下列區域外的所有 Power Apps 區域 ：
     - 美國政府 （GCC）
     - 美國政府（海灣合作委員會高中）
     - 由 21Vianet 營運的中國雲
     - 美國國防部 （DoD）
Power Automate（自動化服務） 進階 除下列區域外的所有 Power Automate 區域 ：
     - 美國政府 （GCC）
     - 美國政府（海灣合作委員會高中）
     - 由 21Vianet 營運的中國雲
     - 美國國防部 （DoD）
連絡人​​
名稱 日軍支援
URL https://www.dayforce.com/resources/help-center#support-for-employers
Email MicrosoftPartnership@dayforce.com
連接器中繼資料
Publisher 日光部隊人工智慧
網站 https://www.dayforce.com/
隱私策略 https://www.dayforce.com/privacy
類別 AI;人力資源

Dayforce HCM

Dayforce HCM 是一個人力資本管理平台。
此連接器提供 Dayforce API 操作，允許您透過員工的外部參考碼（XRefCode）取得其個人資訊（姓名、地址及聯絡方式）。 你可以將這些資料作為工具，用於 Copilot Studio 的 AI 代理，以及其他 Power Platform 情境中。

出版社：Dayforce

先決條件

若要使用此連接器，您需要：

  • 一個 Microsoft Power Platform 環境（例如，使用 Copilot Studio 中的連接器）。
  • 一個活躍 的 Dayforce HCM 環境（QA、UAT 或生產環境）。
  • 一位擁有權限閱讀員工個人資訊的 Dayforce API 使用者 （服務帳號）。
  • 你 Dayforce 環境的 客戶端命名空間 。
    • 此值會以 Dayforce API URL 中的命名空間區段形式出現，例如：
      https://{environmentHost}/{clientNamespace}/V1/...

支援的作業

接頭目前會顯示以下操作。

獲取員工個人信息

行動編號：Get_Employee_Personal_Info
方法：GET

根據員工的 XRefCode 取得經過篩選、簡化的個人資訊視圖。

Request

  • 路徑參數
    • xRefCode （弦，必備）
      要取得員工的外部參考代碼。 該數值必須 與 現有員工的 XRefCode 完全一致;否則，服務會回傳 400 錯誤請求。

在內部，連接器會將通話路由到 Dayforce Employees 用戶端命名空間的端點，並擴充相關的個人資訊，接著由連接器的腳本轉換成簡化的 JSON 物件。

回應

成功（HTTP 200）時，連接器 不會 回傳完整的 Dayforce 員工有效載荷。
取而代之的是，它回傳一個具有以下結構的轉換物件：

{
  "firstName": "string",
  "lastName": "string",
  "addresses": [
    {
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "postalCode": "string",
      "country": "string",
      "state": "string",
      "contactInformationType": "string"
    }
  ],
  "contacts": [
    {
      "personContactId": 0,
      "contactInformationType": "string",
      "electronicAddress": "string",
      "contactNumber": "string",
      "country": "string",
      "effectiveStart": "2024-01-01T00:00:00Z"
    }
  ]
}

更明確地說：

  • 最上層欄位

    • firstName – 員工的名字。
    • lastName – 員工的姓氏。
    • addresses – 一份篩選過的地址條目清單。
    • contacts – 一份篩選過的聯絡人條目清單。

  • 位址物件（addresses[]）

    • address1 – 主要地址線。
    • address2 – 次要地址行。
    • address3 – 附加地址行。
    • city – 城市名稱。
    • postalCode – 郵遞區號或郵遞區號。
    • country – 國家名稱（映射自Dayforce國家名稱）。
    • state – 州名或省名（映射自Dayforce州名）。
    • contactInformationType – 簡短名稱，描述地址類型（例如「家」、「郵寄」），基於 Dayforce 聯絡資訊類型。

  • 接觸物件（contacts[]）

    • personContactId – 聯絡紀錄的內部數字識別碼。
    • contactInformationType – 簡短名稱，描述聯絡方式（例如「行動電話」、「家庭電話」、「工作電子郵件」）。
    • electronicAddress – 針對「線上個人檔案」類型的聯絡人（如電子郵件或其他電子地址）。
    • contactNumber – 用於電話型聯絡人（例如行動電話或市話號碼）。
    • country – 與聯絡人相關的國家價值（如適用）。
    • effectiveStart – 此聯絡資訊的生效起始日期（如有）。

注意：連接器腳本會故意過濾原始的 Dayforce 有效載荷。
只有上述欄位會暴露給呼叫此操作的使用者。

錯誤時，API 會回傳：

  • 400 個錯誤請求 – 因錯誤或無效 xRefCode請求。
  • 500 內部伺服器錯誤 – 用於意外伺服器端故障。

錯誤回應包含來自底層 Dayforce API 的診斷資訊。

取得憑證

此連接器使用 Basic 認證 方式連接 Dayforce API。

取得所需資格：

  1. 在 Dayforce 中建立或識別 API 使用者

    • 請與你的 Dayforce 管理員或實施團隊合作。
    • 確保 API 使用者擁有員工個人資訊的讀取權限，適用於你的環境。

  2. 收集以下數值

    • 使用者名稱 – Dayforce API 用戶名。
    • 密碼 – Dayforce API 密碼。
    • 用戶端命名空間 – 用於 Dayforce API URL 的命名空間值。
      • 這通常是你組織或環境的簡短識別碼，例如出現在以下網址中的細分區塊：
        https://{environmentHost}/{clientNamespace}/V1/Employees/...。

  3. 建立連接器連接時請使用這些數值

    • 在 Power Platform 連線對話框中：
      • 輸入 Dayforce API 使用者 的使用者名稱 和 密碼 。
      • 在「Client Namespace」欄位輸入你的 Dayforce 客戶命名空間 。
    • 連接器利用這些值將請求路由至正確的 Dayforce 租戶並驗證通話。

如果您不確定您的客戶名稱空間或 API 使用者資訊，請聯絡 Dayforce 客服或您內部的 Dayforce 管理員。

使用者入門

建議的測試與使用這個連接器的方法是將它作為 工具加入 Copilot Studio 的 AI 代理程式中。

1. 建立連結

在使用 Copilot Studio 的連接器前，請確認有連接：

  1. 在 Power Platform 管理員或創客體驗中，請前往 資料>連結。
  2. 選取 + 新增連線。
  3. 搜尋你的 Dayforce HCM 連接器（這個連接器）。
  4. 出現提示時，請提供：
    • 用戶名 – Dayforce API 使用者名稱。
    • 密碼 – Dayforce API 使用者密碼。
    • 客戶名稱空間 – 您的 Dayforce 客戶名稱空間。
  5. 保留連線。

2. 在 Copilot Studio 建立 AI 代理，並將連接器作為工具加入

  1. 打開 Copilot Studio。
  2. 建立一個新的 AI 代理 （或開啟一個現有代理，讓你想使用 Dayforce 資料）。
  3. 請前往代理程式的 「工具/插件 （或 連接器）」區塊。
  4. 把你的 Dayforce HCM 連接器當作工具加入。
  5. 確保連接器使用你之前建立的連接方式。

3. 從 AI 代理呼叫連接器

  1. 在你的 AI 代理創作經驗中：
    • 建立或 編輯一個主題、 動作或 外掛呼叫 ，讓你希望代理人取得員工資訊。
  2. 配置一個使用 「取得員工個人資訊 」操作的工具呼叫：
    • 將使用者輸入（例如「員工程式碼」）映射到參數 xRefCode 。
  3. 使用回傳欄位：
    • firstName 並 lastName 可用於 AI 代理的回應中（例如：「這是 John Smith 的地址與聯絡資訊。」）。
    • 在客服邏輯中使用 addresses 和 contacts 來顯示或推理員工的地址和聯絡方式。

此配置讓 AI 代理能安全地呼叫 Dayforce HCM 連接器作為工具，僅取得篩選後的欄位，並將結果納入回應或決策中。

已知問題和限制

  • 僅支援單一員工查詢
    該操作一次為一名員工的資料擷取，依據 XRefCode 進行。 此連接器定義不支援以其他屬性（如名稱或電子郵件）進行批量查詢或搜尋。

  • 需要精確的 XRefCode 匹配
    該 xRefCode 參數必須與現有員工的外部參考代碼完全吻合。 若該值無效或不存在，服務會回傳 400 錯誤請求回應。

  • 唯讀操作
    此版本的連接器為唯讀。 它不支援建立、更新或刪除員工資訊。

  • 環境特定配置
    API 定義與路由政策期望有效的 Dayforce 環境與用戶端命名空間。 如果這些設定與你的實際 Dayforce 環境設定不符，通話將因連線或路由錯誤而失敗。

  • 過濾有效載荷
    底層的 Dayforce API 回傳的欄位遠多於此處顯示的欄位。 連接器的腳本會故意將這些資料過濾並重塑為 firstName、 lastName、 addresses[]、 contacts[] 、

  • 資料可見性取決於 Dayforce 的設定
    回傳給員工的欄位和數值取決於你的 Dayforce 環境設定方式（角色、安全性，以及啟用或填充的資料元素）。

常見問題

問1：「Client Namespace」欄位是用來做什麼的？
用戶端命名空間會在 Dayforce API URL 中識別你的 Dayforce 租戶。 連接器會利用它將請求路由到正確的客戶命名空間，例如：
https://{environmentHost}/{clientNamespace}/V1/Employees/{xRefCode}
如果你不知道這個數值，請聯絡你的 Dayforce 管理員或實施團隊。

Q2：如果我提供無效 xRefCode資料會怎樣？
如果與 xRefCode 現有員工不匹配，服務方會回傳 400 錯誤請求回應。 底層的 Dayforce API 錯誤會透過連接器被發現。

Q3：我可以在一次通話中聯絡多位員工嗎？
用這個連接器定義就不行了。 目前的操作每次通話會根據所提供的 xRefCode資料擷取單一員工的個人資訊。

部署指令（CLI – paconn）

你可以使用 Power Platform Connectors 的 CLIpaconn（）來部署此連接器作為自訂連接器。

1. 準備連接器工件

請確保你在本地資料夾中有以下檔案（例如）： ./dayforce-hcm-connector

  • apiDefinition.swagger.json
  • apiProperties.json
  • script.csx

這些應符合 Power Platform 客製化連接器框架所期望的結構。

2. 安裝並設定 CLI

  1. 如果你還沒安裝 Power Platform Connectors 的 CLIpaconn（），請先安裝。
  2. 根據 Microsoft 的文件（例如，使用 paconn login）登入你的目標環境/租戶paconn。

3. 建立連接器

執行類似的指令：

paconn create   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json --icon icon.png   --script script.csx
  • 請確保你在包含連接器檔案的資料夾中執行這個指令，或提供每個檔案的完整路徑。
  • 建立後，連接器會在你的目標環境中以自訂連接器的形式出現。

4. 更新連接器（如有需要）

如果你之後在 、 apiProperties.json或 script.csx上做修改apiDefinition.swagger.json，你可以用：

paconn update   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json   --script script.csx   --connector-id <your-connector-id>

請替換 <your-connector-id> 成所建立連接器的 ID。

5. 建立連線並在 Copilot Studio 中使用

連接器展開後：

  1. 到 資料>連線 ，使用你的 Dayforce 憑證和客戶端命名空間為 Dayforce HCM 連接器建立新的連線。
  2. 在 Copilot Studio 中，將此連接器作為工具加入你的 AI 客服，並呼叫「 取得員工個人資訊 」操作，如 入門 說明。

6. 安全性與連線共享

我們打算讓這個連接器採用 不可分享的連線模式：當使用 Power App 或 Copilot Studio 代理使用此連接器時，只有連接器 定義 會被共享，且每位使用者必須在首次使用時明確 建立自己的 Dayforce 連線並使用自己的憑證 。 連接器 不得允許以 允許某用戶 Dayforce 權限被另一用戶重複使用的方式共享連線（即應用程式或代理不得以該應用程式擁有者或連線擁有者的 Dayforce 身份執行）。 作為認證的一部分，請確保此連接器的所有認證類型皆設定為 不可共享，因此平台層級會封鎖連線分享，且每位使用者都必須建立自己的 Dayforce 連線。

請附上此免責聲明：此連結不可分享。 如果 Power App 與其他使用者共用，系統會明確提示其他使用者建立新連線。

一旦 Microsoft 認證並發佈，Dayforce HCM 連接器將以認證連接器形式提供，通常只需建立連線（終端用戶無需 CLI 部署）。

正在建立連線

連接器支援下列驗證類型：
預設值 建立連線的參數。 所有地區 不可共享

預設

適用：所有地區

建立連線的參數。

這不是可共用的連線。 如果 Power App 與其他使用者共用，系統會明確提示其他使用者建立新連線。

名稱 類型 說明 Required
使用者名稱 安全字串 此 API 的使用者名稱 對
密碼 安全字串 此 API 的密碼 對
驗證類型 字串 連接 API 的認證類型 對
用戶端命名空間 字串 用戶端命名空間 對

節流限制

名稱 呼叫 續約期間
每個連線的 API 呼叫 100 60 秒

動作

獲取員工個人信息

此操作透過 XRef 碼擷取與員工及其個人（例如姓名、地址及聯絡人）相關的資料

獲取員工個人信息

作業識別碼：
Get_Employee_Personal_Info

此操作透過 XRef 碼擷取與員工及其個人（例如姓名、地址及聯絡人）相關的資料

參數

名稱 機碼 必要 類型 Description
員工參考代碼
 xRefCode True string

要取得員工的唯一識別碼（外部參考碼）。 所提供的數值必須與員工完全吻合;否則，將會回傳錯誤請求（400）。

傳回

身體
Payload_Employee

定義

流程結果

名稱 路徑 類型 Description
Code
 Code string
背景
 Context string
等級
 Level string
Message
 Message string

員工

名稱 路徑 類型 Description
員工編號
 EmployeeId integer
聯繫人
 Contacts PersonContactCollection
地址
 Addresses PersonAddressCollection
全球人ID
 GlobalPersonId string
XRefCode
 XRefCode string
NewXRefCode
 NewXRefCode string
普通名稱
 CommonName string
DisplayName
 DisplayName string
FirstName
 FirstName string
姓氏
 LastName string
首字母
 Initials string
娘家名稱
 MaidenName string
中間名
 MiddleName string
標題
 Title string
最後修改時間戳記
 LastModifiedTimestamp date-time

人物聯絡資料收藏

名稱 路徑 類型 Description
物品
 Items array of PersonContact

人物地址收藏

名稱 路徑 類型 Description
物品
 Items array of PersonAddress

PersonContact

名稱 路徑 類型 Description
人物聯絡ID
 PersonContactId integer
聯絡資訊類型
 ContactInformationType ContactInformationType
聯絡電話
 ContactNumber string
國家
 Country Country
有效結束
 EffectiveEnd date-time
有效開始
 EffectiveStart date-time
電子地址
 ElectronicAddress string
擴充功能
 Extension string
IsForSystemCommunications
 IsForSystemCommunications boolean
IsPreferredContactMethod
 IsPreferredContactMethod boolean
IsUnlistedNumber
 IsUnlistedNumber boolean
格式化編號
 FormattedNumber string
已驗證
 IsVerified boolean
被拒絕了
 IsRejected boolean
ShowRejectedWarning
 ShowRejectedWarning boolean
驗證請求數量
 NumberOfVerificationRequests integer
最後修改時間戳記
 LastModifiedTimestamp date-time

人物地址

名稱 路徑 類型 Description
人物地址ID
 PersonAddressId integer
地址1
 Address1 string
地址2
 Address2 string
地址3
 Address3 string
地址4
 Address4 string
地址5
 Address5 string
地址6
 Address6 string
城市
 City string
郵遞區號
 PostalCode string
國家
 Country Country
State
 State State
聯絡資訊類型
 ContactInformationType ContactInformationType
IsPayrollMailing
 IsPayrollMailing boolean
DisplayOnTaxForm
 DisplayOnTaxForm boolean
顯示在收入報表上
 DisplayOnEarningStatement boolean
有效開始
 EffectiveStart date-time
有效結束
 EffectiveEnd date-time
縣
 County string
最後修改時間戳記
 LastModifiedTimestamp date-time

國家

名稱 路徑 類型 Description
名稱
 Name string
XRefCode
 XRefCode string
ShortName
 ShortName string
長名
 LongName string
最後修改時間戳記
 LastModifiedTimestamp date-time

聯絡資訊類型

名稱 路徑 類型 Description
聯絡資訊類型群組
 ContactInformationTypeGroup ContactInformationTypeGroup
XRefCode
 XRefCode string
ShortName
 ShortName string
長名
 LongName string
最後修改時間戳記
 LastModifiedTimestamp date-time

State

名稱 路徑 類型 Description
名稱
 Name string
XRefCode
 XRefCode string
ShortName
 ShortName string
長名
 LongName string
最後修改時間戳記
 LastModifiedTimestamp date-time

聯絡資訊類型群組

名稱 路徑 類型 Description
XRefCode
 XRefCode string
ShortName
 ShortName string
長名
 LongName string
最後修改時間戳記
 LastModifiedTimestamp date-time

Payload_Employee

名稱 路徑 類型 Description
數據
 Data Employee
流程結果
 ProcessResults array of ProcessResult