Dayforce HCM（預覽）

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

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 環境的 API URL ，包括用戶端命名空間。
  • 這是用來呼叫租戶 Dayforce API 的基礎 URL，例如：
    https://{environmentHost}/{basePath}/api/{clientNamespace}
  • 具體格式取決於你的 Dayforce 環境設定。 若不確定網址，請聯絡您的 Dayforce 管理員。

---

支援的作業

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

獲取員工個人信息

行動編號：Get_Employee_Personal_Info
方法：GET

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

Request

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

在內部，連接器會根據連線建立時提供的 API URL 將呼叫導向 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. 收集以下數值

   • API URL – 你 Dayforce 租戶的基礎 API URL，包含客戶端命名空間。 這是連接器用來路由請求到你的 Dayforce 環境的 URL。 不要包含尾部斜線。

     • 範例：https://{environmentHost}/{basePath}/api/{clientNamespace}

     重要： 部分 Dayforce 環境使用通用 URL（例如 https://dayforcehcm.com/api/{clientNamespace}），該網址會自動導向到特定環境的 URL（例如 https://us252-services.dayforcehcm.com/api/{clientNamespace}）。 設定連接器時，務必使用 最終解析的 URL ，而非通用 URL。 你可以透過瀏覽 Swagger 文件頁面（例如， https://dayforcehcm.com/api/{clientNamespace}/swagger/index.html），並註明瀏覽器被重定向的網址，來判斷最終網址。

   • 使用者名稱 – Dayforce API 用戶名。

   • 密碼 – Dayforce API 密碼。

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

   • 在 Power Platform 連線對話框中：
     • 輸入你 Dayforce 環境的 API URL 。
     • 輸入 Dayforce API 使用者 的使用者名稱 和 密碼 。
   • 連接器會使用 API URL 將請求路由到正確的 Dayforce 租戶，並提供憑證來驗證通話。

如果你不確定你的 API 網址或使用者資訊，請聯絡 Dayforce 客服或你內部的 Dayforce 管理員。

---

使用者入門

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

1. 建立連結

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

1. 在 Power Platform 管理員或創客體驗中，請前往 資料>連結。
2. 選取 + 新增連線。
3. 搜尋你的 Dayforce HCM 連接器（這個連接器）。
4. 出現提示時，請提供：
   • API URL – 你的 Dayforce 租戶（包含客戶端命名空間）的基礎 API URL。 不要包含尾部斜線。
   • 用戶名 – Dayforce API 使用者名稱。
   • 密碼 – Dayforce API 使用者密碼。
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 錯誤請求回應。

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

• 環境特定配置
  連接器需要一個有效的 Dayforce API URL（在連線建立時提供）。 如果網址與你的實際 Dayforce 環境設定不符，通話會因連線或路由錯誤而失敗。 API URL 中請勿包含尾部斜線。

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

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

---

常見問題

問1：「API URL」欄位是用來做什麼的？
API URL 是你 Dayforce 租戶的基礎 URL，包含用戶端命名空間。 連接器會用它將所有 API 請求導向正確的 Dayforce 環境。 網址不應該包含尾部斜線。
如果你不知道這個數值，請聯絡你的 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）登入你的目標環境/租戶paconn login。

3. 建立連接器

執行類似的指令：

paconn create   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json --icon icon.png   --script script.csx

• 請確保你在包含連接器檔案的資料夾中執行這個指令，或提供每個檔案的完整路徑。
• 建立後，連接器會在你的目標環境中以自訂連接器的形式出現。

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

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

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 API URL 和憑證為 Dayforce HCM 連接器建立新連線。
2. 在 Copilot Studio 中，將此連接器作為工具加入你的 AI 客服，並呼叫「 取得員工個人資訊 」操作，如 入門 說明。

6. 安全性與連線共享

此連接器採用 不可共享的連接模式。 當你共用使用 此連接器的 Power App 或 Copilot Studio 代理時，只有連接器 definition 會被共享——每位使用者首次使用時必須建立自己的 Dayforce 連線，並使用自己的憑證。 連線無法以允許另一位使用者重複使用的方式分享連線。 所有認證類型都設定 為不可共享，因此連線共享會在平台層級被阻擋，且每位使用者都必須建立自己的 Dayforce 連線。

節流限制

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

動作

獲取員工個人信息

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

獲取員工個人信息

定義

流程結果

員工

人物聯絡資料收藏

人物地址收藏

PersonContact

人物地址

國家

聯絡資訊類型

State

聯絡資訊類型群組

Payload_Employee