Dayforce HCM (предварительная версия)

Этот соединитель доступен в следующих продуктах и регионах:

Услуга	Класс	Регионы
Copilot Studio	Премиум	Все регионы Power Automate , кроме следующих:      - Правительство США (GCC)      - Правительство США (GCC High)      — Облако Китая, управляемое 21Vianet      - Министерство обороны США (DoD)
Логические приложения	Стандарт	Все регионы Logic Apps , кроме следующих:      — Регионы Azure для государственных организаций      — Регионы Azure Для Китая      - Министерство обороны США (DoD)
Power Apps	Премиум	Все регионы Power Apps , кроме следующих:      - Правительство США (GCC)      - Правительство США (GCC High)      — Облако Китая, управляемое 21Vianet      - Министерство обороны США (DoD)
Power Automate	Премиум	Все регионы Power Automate , кроме следующих:      - Правительство США (GCC)      - Правительство США (GCC High)      — Облако Китая, управляемое 21Vianet      - Министерство обороны США (DoD)

Контакт
Имя	Поддержка Dayforce
URL	https://www.dayforce.com/resources/help-center#support-for-employers
Эл. почта	MicrosoftPartnership@dayforce.com

Метаданные соединителя
Publisher	Dayforce AI
Веб-сайт	https://www.dayforce.com/
Политика конфиденциальности	https://www.dayforce.com/privacy
Категории	AI; Кадровые ресурсы

Dayforce HCM

Dayforce HCM — это платформа управления человеческим капиталом.
Этот соединитель предоставляет операцию API Dayforce, которая позволяет получить личную информацию сотрудника (имя, адреса и контактные данные) по внешнему коду ссылки (XRefCode). Эти данные можно использовать в качестве средства в агентах ИИ Copilot Studio, а также в других сценариях Power Platform.

Издатель: Dayforce

---

Необходимые условия

Чтобы использовать этот соединитель, вам потребуется:

• Среда Microsoft Power Platform (например, для использования соединителя в Copilot Studio).
• Активная среда Dayforce HCM (QA, UAT или Production).
• Пользователь API Dayforce (учетная запись службы) с разрешением на чтение персональных данных сотрудника.
• URL-адрес API для среды Dayforce, включая пространство имен клиента.
  • Это базовый URL-адрес, используемый для вызова API Dayforce для вашего клиента, например:
    https://{environmentHost}/{basePath}/api/{clientNamespace}
  • Точный формат зависит от конфигурации среды Dayforce. Обратитесь к администратору Dayforce, если вы не уверены в URL-адресе.

---

Поддерживаемые операции

Соединитель в настоящее время предоставляет следующую операцию.

Получение персональных сведений о сотрудниках

Идентификатор операции:Get_Employee_Personal_Info
Метод:GET

Извлекает отфильтрованное, упрощенное представление персональных данных для одного сотрудника на основе XRefCode.

запрос

• параметр пути
  • xRefCode (строка, обязательный)
    Внешний справочный код сотрудника, который требуется получить. Значение должно точно соответствовать существующему XRefCode сотрудника; в противном случае служба возвращает недопустимый запрос 400.

Внутри соединителя направляет вызов конечной точки Dayforce Employees с помощью URL-адреса API, предоставленного во время создания подключения, и расширяет соответствующие личные данные, которые затем преобразуются скриптом соединителя в упрощенный объект 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.

• Объект Contact (contacts[])

  • personContactId — внутренний числовой идентификатор записи контакта.
  • contactInformationType — короткое имя, описывающее тип контакта (например, "Мобильный", "Домашний телефон", "Рабочий адрес электронной почты").
  • electronicAddress — для контактов стиля "онлайн-профиль" (например, электронной почты или других электронных адресов).
  • contactNumber — для контактов в стиле телефона (например, номеров мобильных или стационарных телефонов).
  • country — значение страны, связанное с контактом (где применимо).
  • effectiveStart — дата начала действия этих контактных данных (если она доступна).

Примечание. Сценарий соединителя намеренно фильтрует необработанные полезные данные Dayforce.
Только указанные выше поля предоставляются вызывающим службам этой операции.

При ошибке API возвращает:

• 400 Недопустимый запрос — для неправильных запросов или недопустимых xRefCode.
• 500 Внутренняя ошибка сервера — для непредвиденных сбоев на стороне сервера.

Ответы на ошибки включают диагностические сведения из базового API Dayforce.

---

Получение учетных данных

Этот соединитель использует обычную проверку подлинности для подключения к API Dayforce.

Чтобы получить необходимые учетные данные, выполните следующие действия.

1. Создание или идентификация пользователя API в Dayforce

   • Обратитесь к администратору Dayforce или группе реализации.
   • Убедитесь, что пользователь API имеет доступ на чтение к персональным данным сотрудника для вашей среды.

2. Сбор следующих значений

   • URL-адрес API — базовый URL-адрес API для клиента Dayforce, включая пространство имен клиента. Это URL-адрес, который соединитель будет использовать для маршрутизации запросов в среду Dayforce. Не включать косую черту.

     • Пример: https://{environmentHost}/{basePath}/api/{clientNamespace}

     Важно: В некоторых средах Dayforce используется универсальный URL-адрес (например, https://dayforcehcm.com/api/{clientNamespace}), который автоматически перенаправляется на URL-адрес конкретной среды (например, https://us252-services.dayforcehcm.com/api/{clientNamespace}). При настройке соединителя всегда используйте окончательный URL-адрес, а не универсальный URL-адрес. Вы можете определить окончательный URL-адрес, перейдя на страницу документации Swagger для вашей среды (например, https://dayforcehcm.com/api/{clientNamespace}/swagger/index.html) и отметив, что браузер перенаправляется по URL-адресу.

   • Имя пользователя — имя пользователя API Dayforce.

   • Пароль — пароль API Dayforce.

3. Используйте эти значения при создании подключения соединителя

   • В диалоговом окне подключения Power Platform:
     • Введите URL-адрес API для среды Dayforce.
     • Введите имя пользователя и пароль для пользователя API Dayforce.
   • Соединитель использует URL-адрес API для маршрутизации запросов к правильному клиенту Dayforce и учетным данным для проверки подлинности вызова.

Если вы не уверены в URL-адресе API или сведения о пользователе API, обратитесь в службу поддержки Dayforce или внутренний администратор Dayforce.

---

Начало работы

Рекомендуемый способ тестирования и использования этого соединителя — добавить его в качестве средства в агентЕ ИИ Copilot Studio.

1. Создание подключения

Прежде чем использовать соединитель в Copilot Studio, убедитесь, что подключение существует:

1. В интерфейсе администратора или разработчика Power Platform перейдите в раздел"Подключения>".
2. Выберите + Новое подключение.
3. Найдите соединитель Dayforce HCM (этот соединитель).
4. При появлении запроса укажите:
   • URL-адрес API — базовый URL-адрес API для клиента Dayforce (включая пространство имен клиента). Не включать косую черту.
   • Имя пользователя Dayforce API.
   • Пароль — пароль пользователя API Dayforce.
5. Сохраните подключение.

2. Создание агента ИИ в Copilot Studio и добавление соединителя в качестве инструмента

1. Откройте Copilot Studio.
2. Создайте новый агент ИИ (или откройте существующий агент, в котором требуется использовать данные Dayforce).
3. Перейдите в раздел "Сервис", "Подключаемые модули " (или "Соединители") агента.
4. Добавьте соединитель Dayforce HCM в качестве средства.
5. Убедитесь, что соединитель использует созданное ранее соединение.

3. Вызов соединителя из агента ИИ

1. В интерфейсе разработки агента ИИ:
   • Создайте или измените раздел, действие или вызов подключаемого модуля , где требуется, чтобы агент извлекает сведения о сотрудниках.
2. Настройте вызов средства, использующий операцию Get Employee Personal Info :
   • Сопоставить входные данные пользователя (например, "код сотрудника") с параметром xRefCode .
3. Используйте возвращаемые поля:
   • firstName и lastName можно использовать в ответах агента ИИ (например, "Вот адрес и контактные данные Для Джона Смита").
   • Используйте addresses и contacts в логике агента, чтобы отобразить или причину по адресу и контактным данным сотрудника.

Эта настройка позволяет агенту ИИ безопасно вызывать соединитель Dayforce HCM в качестве средства, извлекать только отфильтрованные поля и включать эти результаты в ответы или принятие решений.

---

Известные проблемы и ограничения

• Только поиск одного сотрудника
  Операция извлекает данные для одного сотрудника за раз на основе XRefCode. Массовые запросы или поиск по другим атрибутам (например, имени или электронной почты) не поддерживаются этим определением соединителя.

• Требуется точное соответствие XRefCode
  Параметр xRefCode должен точно соответствовать существующему внешнему справочному коду сотрудника. Если значение недопустимо или не существует, служба возвращает ответ 400 недопустимых запросов.

• Операции только для чтения
  Эта версия соединителя доступна только для чтения. Она не поддерживает создание, обновление или удаление сведений о сотрудниках.

• Конфигурация для конкретной среды
  Для соединителя требуется допустимый URL-адрес API Dayforce (предоставленный во время создания подключения). Если URL-адрес не соответствует фактической конфигурации среды Dayforce, вызовы завершаются ошибкой подключения или маршрутизации. Не включайте конечную косую черту в URL-адрес API.

• Отфильтрованные полезные данные
  Базовый API Dayforce возвращает гораздо больше полей, чем предоставляется здесь. Скрипт соединителя намеренно фильтрует и изменяет эти данные только в firstName, lastNameaddresses[]и contacts[] только.

• Видимость данных зависит от конфигурации Dayforce
  Поля и значения, возвращаемые для сотрудника, зависят от того, как настроена среда Dayforce (роли, безопасность и элементы данных, которые включены или заполнены).

---

Часто задаваемые вопросы

Вопрос 1. Для чего используется поле "URL-адрес API"?
URL-адрес API — это базовый URL-адрес клиента Dayforce, включая пространство имен клиента. Соединитель использует его для маршрутизации всех запросов API в правильную среду Dayforce. URL-адрес не должен содержать косую черту.
Если вы не знаете это значение, обратитесь к администратору Dayforce или группе реализации.

Вопрос 2. Что произойдет, если указать недопустимое xRefCodeзначение?
xRefCode Если он не соответствует существующему сотруднику, служба возвращает ответ 400 bad request. Ошибка API Dayforce возникает через соединитель.

Вопрос 3. Можно ли получить несколько сотрудников в одном вызове?
Не с этим определением соединителя. Текущая операция извлекает личную информацию одного сотрудника на звонок на основе предоставленного xRefCode.

---

Инструкции по развертыванию (CLI — paconn)

Этот соединитель можно развернуть в качестве настраиваемого соединителя с помощью интерфейса командной строки Power Platform Connectors (paconn).

1. Подготовка артефактов соединителя

Убедитесь, что в локальной папке есть следующие файлы (например, ./dayforce-hcm-connector):

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

Они должны соответствовать структуре, ожидаемой пользовательской платформой соединителя Power Platform.

2. Установка и настройка интерфейса командной строки

1. Установите интерфейс командной строки соединителей Power Platform (paconn), если вы еще не сделали этого.
2. Войдите в целевую среду или клиент, используя 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> идентификатор созданного соединителя.

5. Создание подключения и его использование в Copilot Studio

После развертывания соединителя:

1. Перейдите кподключениям к > и создайте новое подключение для соединителя Dayforce HCM с помощью URL-адреса и учетных данных API Dayforce.
2. В Copilot Studio добавьте этот соединитель в качестве средства в агент ИИ и вызовите операцию Get Employee Personal Info , как описано в разделе "Начало работы ".

6. Общий доступ к безопасности и подключению

Этот соединитель использует модель подключения, не доступную для общего доступа. При совместном использовании агента Power App или Copilot Studio, использующего этот соединитель, используется только соединитель definition — пользователь each должен создать собственное подключение Dayforce с собственными учетными данными при первом использовании. Подключения нельзя совместно использовать таким образом, чтобы разрешения Dayforce одного пользователя были повторно использованы другим пользователем. Все типы проверки подлинности настроены как недоступные для общего доступа, поэтому общий доступ к подключениям блокируется на уровне платформы, и каждому пользователю всегда требуется установить собственное подключение Dayforce.

Ограничения регулирования

Имя	Вызовы	Период обновления
Вызовы API для каждого подключения	100	60 секунд

Действия

Получение персональных сведений о сотрудниках

Эта операция извлекает данные, связанные с сотрудником и его личными данными (например, "Имена", "Адреса" и "Контакты") по XRef Code

Получение персональных сведений о сотрудниках

Определения

ProcessResult

Сотрудник

PersonContactCollection

PersonAddressCollection

PersonContact

PersonAddress

Страна

ContactInformationType

Государство

ContactInformationTypeGroup

Payload_Employee