Dayforce HCM （预览版）

此连接器在以下产品和区域中可用：

Service	Class	区域
Copilot Studio	高级	除以下各项外的所有 Power Automate 区域 ：      - 美国政府 （GCC）      - 美国政府 （GCC High）      - 由世纪互联运营的中国云      - 美国国防部（DoD）
逻辑应用程序	标准	除以下各项外的所有 逻辑应用区域 ：      - Azure 政府区域      - Azure 中国区域      - 美国国防部（DoD）
Power Apps	高级	除以下各项外的所有 Power Apps 区域 ：      - 美国政府 （GCC）      - 美国政府 （GCC High）      - 由世纪互联运营的中国云      - 美国国防部（DoD）
Power Automate	高级	除以下各项外的所有 Power Automate 区域 ：      - 美国政府 （GCC）      - 美国政府 （GCC High）      - 由世纪互联运营的中国云      - 美国国防部（DoD）

联系人
名称	Dayforce 支持
URL	https://www.dayforce.com/resources/help-center#support-for-employers
Email	MicrosoftPartnership@dayforce.com

连接器元数据
发布者	Dayforce AI
网站	https://www.dayforce.com/
隐私策略	https://www.dayforce.com/privacy
类别	艾;人力资源

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 环境配置。 如果不确定 URL，请联系 Dayforce 管理员。

---

支持的作

连接器当前公开以下操作。

获取员工个人信息

操作 ID：Get_Employee_Personal_Info
方法：GET

根据 XRefCode 检索单个员工的经过筛选的简化个人信息视图。

请求

• 路径参数
  • 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 中的诊断信息。

---

获取凭据

此连接器使用 基本身份验证 连接到 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），并指出浏览器重定向到的 URL 来确定最终 URL。

   • 用户名 – Dayforce API 用户名。

   • 密码 – Dayforce API 密码。

3. 创建连接器连接时使用这些值

   • 在 Power Platform 连接对话框中：
     • 输入 Dayforce 环境的 API URL 。
     • 输入 Dayforce API 用户的用户名和密码。
   • 连接器使用 API URL 将请求路由到正确的 Dayforce 租户，并使用凭据对调用进行身份验证。

如果不确定 API URL 或 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（在创建连接时提供）。 如果 URL 与实际的 Dayforce 环境配置不匹配，则调用将失败并出现连接或路由错误。 不要在 API URL 中包含尾部斜杠。

• 筛选的有效负载
  基础 Dayforce API 返回的字段数多于此处公开的字段。 连接器的脚本有意筛选并重新定义此数据firstName，lastNameaddresses[]并且contacts[]仅对这些数据进行重新调整。

• 数据可见性取决于 Dayforce 配置
  为员工返回的字段和值取决于 Dayforce 环境的配置方式（角色、安全性以及启用或填充哪些数据元素）。

---

常见问题解答

问 1：用于什么“API URL”字段？
API URL 是 Dayforce 租户（包括客户端命名空间）的基本 URL。 连接器使用它将所有 API 请求路由到正确的 Dayforce 环境。 URL 不应包含尾部斜杠。
如果不知道此值，请联系 Dayforce 管理员或实施团队。

问 2：如果我提供无效 xRefCode，会发生什么情况？
如果与 xRefCode 现有员工不匹配，该服务将返回 400 错误的请求响应。 基础 Dayforce API 错误通过连接器显示。

问 3：是否可以在一次呼叫中检索多个员工？
不使用此连接器定义。 当前操作根据提供 xRefCode的每个调用检索单个员工的个人信息。

---

部署说明 （CLI - paconn）

可以使用 Power Platform Connectors CLI（paconn）将此连接器部署为自定义连接器。

1.准备连接器项目

确保本地文件夹中有以下文件（例如 ./dayforce-hcm-connector：

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

它们应与 Power Platform 自定义连接器框架预期的结构匹配。

2.安装和配置 CLI

1. 安装 Power Platform Connectors CLI（paconn如果尚未安装）。
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 - each 用户必须使用自己的凭据创建自己的 Dayforce 连接。 无法以允许一个用户的 Dayforce 权限被另一个用户重复使用的方式共享连接。 所有身份验证类型都配置为 不可共享，因此在平台级别阻止连接共享，并且始终要求每个用户建立自己的 Dayforce 连接。

正在创建连接

连接器支持以下身份验证类型：

默认	用于创建连接的参数。	所有区域	不可共享

违约

适用：所有区域

用于创建连接的参数。

这是不可共享的连接。 如果 Power App 与另一个用户共享，系统会提示其他用户显式创建新连接。

名称	类型	说明	必需
用户名	securestring	此 API 的用户名	True
密码	securestring	此 API 的密码	True
身份验证类型	字符串	用于连接到 API 的身份验证类型	True
客户端命名空间	字符串	客户端命名空间	True

限制

名称	调用	续订期
每个连接的 API 调用数	100	60 秒

操作

获取员工个人信息

此操作通过 XRef Code 检索与员工及其个人（例如姓名、地址和联系人）信息相关的数据

获取员工个人信息

定义

ProcessResult

员工

PersonContactCollection

PersonAddressCollection

PersonContact

PersonAddress

国家

ContactInformationType

州

ContactInformationTypeGroup

Payload_Employee