Создание настраиваемой интеграции для синхронизации системы управления персоналом с помощью смен

Статья
11/18/2024
Применяется к:

Microsoft Teams, Microsoft 365 for frontline workers

Обзор

Интегрируйте shifts, приложение управления расписанием в Microsoft Teams, с системой управления персоналом (WFM). Благодаря этой интеграции сотрудники первой линии могут просматривать расписания и управлять ими непосредственно в сменах.

В этой статье описано, как создать соединитель с помощью microsoft API Graph для упрощения этой интеграции.

Вы можете настроить интеграцию для односторонняя или двусторонняя синхронизация данных.

Односторонняя синхронизация (WFM системы с shifts). В этой настройке данные расписания в системе WFM синхронизируются с shifts. Соединитель считывает данные в системе WFM и записывает их в shifts. Однако все изменения, внесенные пользователями в смены, не отражаются в системе WFM.
Двусторонняя синхронизация (WFM системные и смены): эта настройка позволяет выполнять двунаправленную синхронизацию. Данные расписания в системе WFM синхронизируются с shifts, а все изменения, внесенные пользователями в смены, синхронизируются с системой WFM. Соединитель проверяет и утверждает изменения, внесенные пользователями в shifts, в соответствии с бизнес-правилами, применяемыми системой WFM, прежде чем изменения будут записаны в Shifts.

Примечание.

Если вы используете ukg Pro WFM, Blue Yonder WFM или Reflexis WFM, вы также можете использовать управляемый соединитель для интеграции Shifts с системой WFM. Дополнительные сведения см. в разделе Соединители смен.

Терминология, используемая в этой статье

Термин	Описание
соединитель	Приложение, которое синхронизирует данные расписания между системой WFM и shifts.
интеграция с персоналом	Сущность, которая определяет метод шифрования для обмена данными, URL-адрес обратного вызова для соединителя и сущности Shifts для синхронизации.

Перед началом работы

Предварительные условия

Определите, какие данные нужно синхронизировать в соответствии с бизнес-потребностями.
Основные понятия проверки подлинности и авторизации в платформа удостоверений Майкрософт. См . раздел Основы проверки подлинности и авторизации.
Администратор обязательные роли:
- По крайней мере администратор облачных приложений для регистрации приложения в Центр администрирования Microsoft Entra
- Глобальный администратор для регистрации интеграции рабочей силы

Знакомство с процессом интеграции

Ниже приведены общие сведения о шагах интеграции. Просмотрите эти сведения, чтобы получить представление об общем процессе, в том числе о том, кто выполняет каждый шаг.

Шаг	Односторонняя синхронизация	Двусторонняя синхронизация	Кто выполняет этот шаг
1	Создайте соединитель: Шаг 1a. Синхронизация изменений, внесенных в shifts, в систему WFM Реализация конечной точки /connect Реализуйте конечную точку /update и делайте смены только для чтения Шаг 1b. Синхронизация данных из системы WFM в shifts	Создайте соединитель: Шаг 1a. Синхронизация изменений, внесенных в shifts, в систему WFM Реализация конечной точки /connect Реализация конечной точки /update Шаг 1b. Синхронизация данных из системы WFM в shifts	Developer
2	Регистрация приложения в Центр администрирования Microsoft Entra	Регистрация приложения в Центр администрирования Microsoft Entra	Учетная запись, которая является по крайней мере администратором облачных приложений;
3	Создание команд и расписаний для синхронизации	Создание команд и расписаний для синхронизации	Разработчик или администратор Teams
4	Зарегистрируйте и включите интеграцию сотрудников: Шаг 4a . Регистрация интеграции рабочей силы в клиенте Шаг 4b. Включение интеграции сотрудников для расписаний команды	Зарегистрируйте и включите интеграцию сотрудников: Шаг 4a . Регистрация интеграции рабочей силы в клиенте Шаг 4b. Включение интеграции сотрудников для расписаний команды	Шаг 4a. Глобальный администратор Шаг 4b. Разработчик

Шаг 1. Создание соединителя

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

Шаг 1a. Синхронизация изменений, внесенных в shifts, в систему WFM
Шаг 1b. Синхронизация данных из системы WFM в shifts

Шаг 1a. Синхронизация изменений, внесенных в shifts, в систему WFM

Чтобы настроить соединитель для получения и обработки запросов из Shifts, необходимо реализовать следующие конечные точки:

/connect (обязательно)
/update (обязательно)
/read (необязательно)

Определение базовых URL-адресов и URL-адресов конечных точек

Базовым URL-адресом (веб-перехватчиком) является {url}/v{apiVersion}, где url иapiVersion — это свойства, заданные в объекте workforceIntegration при регистрации интеграции рабочей силы.

Ниже перечислены относительные пути URL-адресов конечных точек.

/соединять: /connect
/обновлять: /teams/{teamid}/update
/читать: /teams/{teamid}/read

Например, если url-адрес имеет значение https://contosoconnector.com/wfi , а apiVersion — :1

Базовый URL-адрес — https://contosoconnector/com/wfi/v1.
Конечная точка /connect — https://contosoconnector/wfi/v1/connect.
Конечная точка /update — https://contosoconnector/wfi/v1/teams/{teamid}/update.
Конечная точка /read — https://contosoconnector/wfi/v1/teams/{teamid}/read.

Шифрование

Все запросы шифруются с помощью AES-256-CBC-HMAC-SHA256. Общий секретный ключ указывается при регистрации интеграции рабочей силы. Ответы, отправляемые обратно в shifts, не должны шифроваться.

Конечные точки

POST /connect

Shifts вызывает эту конечную точку для проверки подключения при регистрации интеграции рабочей силы. Ответ успешного выполнения возвращается только в том случае, если эта конечная точка возвращает HTTP-ответ 200 OK .

Пример

Запрос
ConnectRequest

{
   "tenantId": "a1s2s355-a2s3-j7h6-f4d3-k2h9j4mqpz",
   "userId": "4fbc12d7-1234-56ef-8a90-bc123d45678f"
}

Отклик
Возврат HTTP 200 OK

POST /teams/{teamid}/update

Смены вызывает эту конечную точку для получения утверждения при изменении сущности Shifts в расписании , включаемом для интеграции рабочей силы. Если эта конечная точка утверждает запрос, изменение сохраняется в shifts.

Так как система WFM является системой записи, когда соединитель получает запрос к этой конечной точке, он должен сначала попытаться внести изменения в систему WFM. Если изменение выполнено успешно, вернитесь к успешному завершению. В противном случае произойдет сбой возврата.

Смены вызывают эту конечную точку для каждого изменения (включая изменения, инициированные из соединителя или WFM системы). Если соединитель отправил обновление в Shifts с помощью API Graph и добавил X-MS-WFMPassthrough: workforceIntegratonId заголовок, запрос, поступающий в эту конечную точку, будет иметь тот же заголовок, что позволяет идентифицировать и обрабатывать эти запросы соответствующим образом. Например, успешное возвращение без внесения изменений в систему WFM, как это было бы избыточно и может привести к тому, что соединитель зависнет в бесконечном цикле.

На следующей схеме показан поток данных.

Примечание.

Дополнительные сведения о моделях запросов и ответов см. в статье WfiRequest раздела Справочник по конечной точке этой статьи.

Возвращаемый код ответа
Любой ответ из интеграции, включая ошибку, должен иметь код 200 OKHTTP-ответа . Текст ответа должен иметь состояние и сообщение об ошибке, отражающие соответствующее состояние ошибки вложенного вызова. Любой ответ от интеграции, отличный 200 OK от , обрабатывается как ошибка и возвращается вызывающей объекту (клиенту или Microsoft Graph).

Если вы хотите настроить односторонную синхронизацию, сделайте shifts доступны только для чтения.

Для односторонной синхронизации необходимо сделать Shift только для чтения, чтобы пользователи не могли вносить изменения в shifts. Чтобы сделать shift-файлы доступны только для чтения, верните ответ на сбой для всех запросов из Shifts.

Например, чтобы запретить пользователям вносить изменения в расписание, эта конечная точка должна возвращать ответ на сбой при получении запроса относительно сущности shift .

Пример

Запрос
WfiRequestContainer

В следующем примере показан запрос из Shifts, который спрашивает, можно ли сохранить в shifts с идентификатором SHFT_12345678-1234-1234-1234-1234567890ab со свойствами, указанными в тексте. Этот запрос активировался, когда пользователь создает смену в shifts.

{
  "requests": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "method": "POST",
      "url": "/shifts/SHFT_12345678-1234-1234-1234-1234567890ab",
      "headers": {
        "X-MS-Transaction-ID": "1",
        "X-MS-Expires": "2024-10-11T21:27:59.0134605Z"
      },
      "body": {
        "draftShift": {
          "activities": [],
          "isActive": true,
          "startDateTime": "2024-10-12T15:00:00.000Z",
          "endDateTime": "2024-10-12T17:00:00.000Z",
          "theme": "Blue"
        },
        "isStagedForDeletion": false,
        "schedulingGroupId": "TAG_a3e0b3f1-4a5c-4c2e-8eeb-5b8c3d1e3f8b",
        "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "createdDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedBy": {
          "user": {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "displayName": "Adele Vance"
          }
        },
        "id": "SHFT_12345678-1234-1234-1234-1234567890ab"
      }
    }
  ]
}

Отклик
WfiResponse

Успешно: возврат HTTP 200 OK

В этом примере показан ответ, возвращаемый, если конечная точка одобрила запрос. В этом сценарии смена сохраняется в shifts, и пользователь может увидеть сдвиг в расписании.

{
  "responses": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "status": 200,
      "body": {
        "eTag": "3f4e5d6c-7a8b-9c0d-1e2f-3g4h5i6j7k8l",
        "error": null,
        "data": null
      }
    }
  ]
}

Сбой: возврат HTTP 200 OK

В этом примере показан ответ, возвращаемый, если конечная точка отклонила запрос. В этом сценарии пользователь получает сообщение об ошибке "Не удалось добавить сдвиг" в shifts.

{
    "responses": [
        {
            "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
            "status": 500,
            "body": {
                "error": {
                    "code": "500",
                    "message": “Could not add the shift”
                },
                "data": null
            }
        }
    ]
}

POST /teams/{teamid}/read

Эта конечная точка обрабатывает запросы из shifts для получения допустимых причин отгула или допустимых смен для запросов на переключение для пользователя.

Примечание.

По состоянию на октябрь 2024 г. эта конечная точка поддерживается только в бета-версии microsoft API Graph. Также необходимо указать значения для свойства eligibilityFilteringEnabledEntities при регистрации интеграции рабочей силы.

На следующей схеме показан поток данных.

Возвращаемый код ответа
Любой ответ из интеграции, включая ошибку, должен иметь код 200 OKHTTP-ответа . Текст ответа должен содержать состояние и сообщение об ошибке, отражающие соответствующее состояние ошибки вложенного вызова. Любой ответ от интеграции, отличный 200 OK от , обрабатывается как ошибка и возвращается вызывающей объекту (клиенту или Microsoft Graph).

Пример: TimeOffReason

Запрос

В следующем примере показан запрос из Shifts, который задает причину отгула для пользователя (идентификатор пользователя aa162a04-bec6-4b81-ba99-96caa7b2b24d). Этот запрос активировался, когда пользователь запрашивает отгул в shifts.

 { 
  "requests": [ 
    { 
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
      "method": "GET", 
      "url": "/users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason"
    } 
  ] 
}

Отклик
Успешно: возврат HTTP 200 OK

В следующем ответе показано, что допустимые идентификаторы причин отгула для пользователя: "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" и "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". В этом сценарии пользователь видит соответствующие причины отгула в сменах.

{
    "responses": [ 
      { 
        "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
        "status": 200, 
        "body": { 
          "data": [ 
            "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc", 
            "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d" 
          ], 
          "error": null 
          } 
        }
    ]
}

Сбой: возврат HTTP 200 OK

В этом примере возвращается ответ об ошибке, так как соединителю не удалось связаться с системой WFM, чтобы получить причину отгула для пользователя.

 {
  "responses": [
    {
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "Could not reach WFM"
        }
      }
    }
  ]
}

Пример: SwapRequest

Запрос

В следующем примере показан запрос из Shifts, который задает, какие смены могут быть заменены с идентификатором смены SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 с 2024 по 2024 г. 10-01T04:00:00.000000Z и 2024-11-01T03:59:59.9990000Z.

{
  "requests": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "method": "GET",
      "url": "/shifts/SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029/requestableShifts?requestType=SwapRequest&startTime=2024-10-01T04:00:00.0000000Z&endTime=2024-11-01T03:59:59.9990000Z"
    }
  ]
}

Отклик
Успешно: возврат HTTP 200 OK

В следующем ответе показано, что смена может быть заменена на смену, идентификатор которой SHFT_98e96e23-966b-43be-b90d-4697037b67af.

{ 
  "responses": [ 
    { 
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029", 
      "status": 200, 
      "body": { 
        "data": ["SHFT_98e96e23-966b-43be-b90d-4697037b67af"],
        "error": null, 
      } 
    }
  ]
}

Сбой: возврат HTTP 200 OK

В этом примере возвращается ответ об ошибке, так как соединителю не удалось связаться с системой WFM, чтобы получить подходящие смены для запроса на переключение для пользователя.

{
  "responses": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "could not reach WFM"
        }
      }
    }
  ]
}

Шаг 1b. Синхронизация данных из системы WFM в shifts

Используйте API-интерфейсы Shifts в Microsoft Graph для чтения данных расписания из системы WFM и записи данных в shifts.

Например, чтобы добавить shift в shifts, используйте API создания смен .

Ознакомьтесь со справочником по API-интерфейсам смен microsoft API Graph версии 1.0, которые перечислены в разделе Управление сменами.

Примечание.

Заголовок MS-APP-ACTS-AS является обязательным в запросах и должен содержать идентификатор (GUID) пользователя, от имени пользователя, от имени в котором работает приложение. При обновлении расписания рекомендуется использовать идентификатор пользователя владельца команды.

На следующей схеме показан поток данных.

Начальная синхронизация

Для первой синхронизации соединитель должен считывать данные в системе WFM и записывать данные в shifts. Мы рекомендуем синхронизировать данные за две недели в будущем.

После начальной синхронизации

После первой синхронизации можно выбрать следующее:

Синхронное обновление смен с изменениями в системе WFM. Отправьте обновление в shifts для каждого изменения, внесенного в систему WFM.
Асинхронное обновление смен с изменениями в системе WFM. Выполняйте периодическую синхронизацию, записывая все изменения, произошедшие в системе WFM в течение определенного периода времени (например, 10 минут) в shifts.

Все операции записи в shifts, включая операции записи, инициированные соединителем, вызывают вызов конечной точки /update соединителя. Рекомендуется включать X-MS-WFMPassthrough: workforceIntegratonId заголовок для всех вызовов записи, чтобы соединитель идентифицировать и обрабатывать их соответствующим образом. Например, если система WFM инициировала изменение, подтвердите его, не применяя обновление к системе WFM.

Примечание.

Если вы настраиваете соединитель для двусторонней синхронизации данных между системой WFM и shifts, исключите изменения, инициированные из shifts, в периодической синхронизации. Эти изменения уже написаны в shifts.

Шаг 2. Регистрация приложения в Центр администрирования Microsoft Entra

Выполните следующие действия, чтобы зарегистрировать приложение для соединителя в платформа удостоверений Майкрософт, настроить разрешения для приложения на доступ к Microsoft Graph и получить маркер доступа.

Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.
Регистрация приложения. Инструкции см. в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт.
Назначьте приложению разрешенияSchedule.ReadWrite.All для доступа только к приложению и получите маркер доступа.

Пошаговые инструкции см. в статье Получение доступа без пользователя.

Маркер доступа проверяет, разрешено ли ваше приложение вызывать Microsoft Graph с помощью собственного удостоверения с помощью разрешения Schedule.ReadWrite.All . Он должен быть включен в заголовок авторизации запросов.

Шаг 3. Создание команд и расписаний для синхронизации

Настройте команды в Teams, которые нужно синхронизировать. Вы можете использовать существующие команды или создавать новые команды.

Настройте команды в Teams так, чтобы они соответствовали командам и расположениям в вашей системе WFM. Обязательно добавьте в каждую команду следующих пользователей:
- Руководители первой линии в качестве владельцев команд. Убедитесь, что вы добавили пользователя в MS-APP-ACTS-AS заголовок в качестве владельца каждой соответствующей команды.
- Сотрудники первой линии в качестве членов команды.
Создайте расписание в разделе Смены для каждой команды. Дополнительные сведения см. в статье Создание или замена расписания.
Добавьте группы расписания в расписание в каждой команде. Группы расписания используются для группирования сотрудников на основе общих характеристик в команде. Например, группы расписания могут быть отделами или типами заданий. Дополнительные сведения см. в разделе Тип ресурса schedulingGroup.
Добавление сотрудников в каждую группу расписания. Дополнительные сведения см. в разделе Замена schedulingGroup.

Примечание.

Вы также можете использовать Центр администрирования Teams для настройки команд и развертывания смен в командах. Дополнительные сведения см. в статьях

Шаг 4. Регистрация и включение интеграции с персоналом

Интеграция рабочей силы определяет параметры шифрования для обмена данными между shifts и соединителем, URL-адрес для обратных вызовов из shifts и типы сущностей для синхронизации.

Чтобы зарегистрировать и включить интеграцию сотрудников, выполните следующие действия.

Шаг 4a. Регистрация интеграции сотрудников
Шаг 4b. Включение интеграции сотрудников для расписаний команды

Шаг 4a. Регистрация интеграции рабочей силы в клиенте

Для выполнения этого шага необходимо быть глобальным администратором.

Используйте API create workforceIntegration , чтобы зарегистрировать интеграцию сотрудников в клиенте.

Ниже приведен пример запроса.

POST https://graph.microsoft.com/v1.0/teamwork/workforceIntegrations/
{ 
  "displayName": "Contoso integration", 
  "apiVersion": 1, 
  "encryption": { 
    "protocol": "sharedSecret", 
    "secret": "secret-value" 
  }, 
  "isActive": true, 
  "url": "https://contosoconnector.com/wfi", 
  "supportedEntities": "Shift,SwapRequest,UserShiftPreferences,Openshift,OpenShiftRequest,OfferShiftRequest”,
}

Дополнительные сведения см. в следующей таблице. Дополнительные сведения см. в статье Тип ресурса workforceIntegration.

Property	Дополнительная информация
apiVersion	Версия API для URL-адреса обратного вызова. Базовый URL-адрес состоит из свойства url и этого свойства.
шифрование	Присвойте протоколу значение `sharedSecret`. Значение секрета должно содержать ровно 64 символа. Используйте секрет для расшифровки зашифрованных полезных данных JSON, которые отправляются в конечную точку соединителя из shifts. Полезные данные шифруются с помощью AES-256-CBC-HMAC-SHA256. Приложение должно безопасно сохранить этот секрет. Например, в хранилище ключей.
supportedEntities	Укажите сущности Shifts, которые соединитель будет поддерживать для синхронизации. Shifts вызывает конечную точку /update соединителя при изменении любой из этих сущностей, чтобы можно было утвердить или отклонить изменение. Список возможных значений см. в разделе Тип ресурса workforceIntegration. Заметка Этот список является изменяемым перечислением. Чтобы получить все значения, `Prefer: include-unknown-enum-members` необходимо использовать заголовок запроса.
eligibilityFilteringEnabledEntities	Примечание. По состоянию на октябрь 2024 г. эта конечная точка поддерживается только в бета-версии microsoft API Graph. Укажите сущности Shifts, которые необходимо соединительно поддерживать фильтрацию по допустимости. Возможные значения: `none`: пустой список `SwapRequests`: shifts вызывает конечную точку /read соединителя для получения отфильтрованного списка смен, которые пользователь может выбрать для запроса на переключение. `TimeOffReasons`: shifts вызывает конечную точку /read соединителя, чтобы получить отфильтрованный список причин, по которым пользователь может выбрать, когда запрашивает отгул. Заметка Этот список является изменяемым перечислением. Чтобы получить все значения, `Prefer: include-unknown-enum-members` необходимо использовать заголовок запроса.
url	URL-адрес интеграции рабочей силы для обратных вызовов из смен. Базовый URL-адрес состоит из этого свойства и свойства apiVerson .

Шаг 4b. Включение интеграции сотрудников для расписаний команды

Включите интеграцию сотрудников в расписаниях, которыми вы хотите управлять. Для этого используйте API создания или замены расписания , чтобы создать или обновить расписание для команд.

Ниже приведен пример запроса.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}

Укажите идентификатор workforceIntegrationId, созданный при регистрации интеграции с персоналом.
Вы можете включить не более одной интеграции сотрудников по расписанию. Если в запрос включается более одного объекта workforceIntegrationId, используется первый.

Устранение неполадок

Connector

Когда соединитель отвечает на запрос из Shifts, что произойдет, если он возвращает код ответа, отличный от 200? Имеет ли значение, если возвращается состояние, отличное от 200 в тексте ответа?

Между этими двумя сценариями существует разница.

Если соединитель возвращает код ответа, отличный от 200, shifts пытается повторить попытку /read и /update конечных точек несколько раз. В конце концов, shifts отображает "Что-то пошло не так. Настройка интеграции рабочей силы в вашей команде ответила недопустимыми данными".
Если соединитель возвращает в тексте ответа состояние, отличное от 200, функция SHIFTS отображает сообщение "Что-то пошло не так. К сожалению, не удалось выполнить изменение", сообщение об ошибке и прекращает повторную попытку конечных точек.

Что произойдет, если соединитель возвращает недопустимые данные в тексте ответа?

Смена пытается повторить конечную точку /read и /update несколько раз. В конце концов, shifts отображает "Что-то пошло не так. Интеграция сотрудников, настроенная в вашей команде, ответила недопустимыми данными".

Разделы справки определить, был ли запрос изначально выполнен в сменах или в системе WFM, чтобы предотвратить бесконечный цикл?

X-MS-WFMPassthrough: workforceIntegratonId Добавьте заголовок во все вызовы записи и обновления, чтобы идентифицировать или игнорировать изменения, инициируемые соединителем. Этот заголовок используется для указания того, что запрос выполнен из-за предыдущего вызова, выполненного соединителем для API Graph для синхронизации данных из системы WFM с shifts.

Регистрация интеграции с персоналом

Я зарегистрировал интеграцию рабочей силы и указал "приемлемостьFilteringEnabledEntities", включая "SwapRequest, OfferShiftRequest и TimeOffReason", но текст ответа не отображает список "приемлемостьFilteringEnabledEntities".

Фильтрация допустимости в настоящее время поддерживается через конечную точку https://graph.microsoft.com/beta , а не конечную точку https://graph.microsoft.com/v1 .

Я зарегистрировал интеграцию с персоналом и добавил "supportedEntities", но получил ответ 400 неверных запросов и "Недопустимые полезные данные: запрошенное значение "shift, ...." сообщение не найдено."

Убедитесь, что каждая сущность Shifts в тексте supportedEntities запроса списка начинается с прописной буквы. Например, "supportedEntities":"Shift,SwapRequest,OpenShift".

Я зарегистрировал интеграцию сотрудников и реализовал конечные точки /connect, /update и /read, но веб-перехватчик не работает.

Убедитесь, что для расписания группы включена интеграция сотрудников. Кроме того, проверка, что свойства url и apiVersion верны.

Справочник по конечной точке

Запрос

ConnectRequest

Свойство	Тип	Описание
tenantId	String	Идентификатор клиента для интеграции рабочей силы
userId	String	Идентификатор пользователя для интеграции рабочей силы

{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Свойство	Тип	Описание
Запросы	Коллекция WfiRequest	Список WfiRequests

{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

Количество элементов в запросе:

В большинстве случаев запрос содержит один элемент.
Некоторые запросы, например утверждения запросов на смену подкачки, имеют пять элементов: один запрос переключения PUT, две смены DELETE (существующие смены) и две смены POST (новые смены).

WfiRequest

Свойство	Тип	Описание
id	String	Идентификатор сущности
метод	String	Метод, вызываемый для элемента. Например, `POST`, `PUT`, `GET`, `DELETE`.
url	String	Указывает тип сущности и сведения об операции.
заголовки	WfiRequestHeader	Заголовки
body	ShiftsEntity	Текст сущности, связанной с запросом.

Для POST /teams/{teamId}/update

Свойство	Тип	Описание
id	String	Идентификатор сущности
метод	String	`POST` для создания сущности, `PUT` для обновления сущности, `DELETE` для удаления сущности.
url	String	Представлено в формате `/{EntityType}/{EntityId}`. Возможные значения для `{EntityType}` : `shifts`, `swapRequests`, `timeoffReasons`, `openshifts`, `openshiftrequests`, `offershiftrequests`, `timesoff`, . `timeOffRequests` Например, `/shifts/SHFT_12345678-1234-1234-1234-1234567890ab`.
заголовок	WfiRequestHeader	Заголовок
body	ShiftsEntity	Должен совпадать `{EntityType}` в свойстве URL-адреса . Используйте параметр shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Например, `/shifts/SHFT_12345678-1234-1234-1234-1234567890ab`.

Для POST /teams/{teamsId}/read

Свойство	Тип	Описание
id	String	Идентификатор сущности
метод	String	Всегда `GET`.
url	String	TimeOffReasons: формат : `/users/{userId}/timeOffReasons?requestType=TimeOffReason`. Например, `/users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason`. SwapRequest: формат : `/shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}`. Например, `shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z`.
заголовок	WfiRequestHeader	Заголовок
body	ShiftsEntity	Всегда `null`.

WfiRequestHeader

Свойство	Тип	Описание
X-MS-Transaction-ID	String	Идентификатор транзакции
X-MS-Expires	String (DateTime)	Дата и время окончания срока действия транзакции

X-MS-WFMPassthrough: workforceIntegratonId не будет включен в WfiRequestHeader. Он должен быть извлечен из httpRequest.

Отклик

WfiResponseContainer

Свойство	Тип	Описание
Ответы	Коллекция WfiResponse	Список WfiResponses

{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Свойство	Тип	Описание
id	String	Идентификатор сущности
status	String	Результат операции
body	WfiResponseBody	WfiResponseBody

WfiResponseBody

Свойство	Тип	Описание
eTag	String	eTag
error	WfiResponseError	Сведения об ошибке
data	String	Запрошенные данные (для запросов на чтение)

WfiResponseError

Свойство	Тип	Описание
code	String	Код ошибки
message	String	Сообщение об ошибке

Поделиться через

Создание настраиваемой интеграции для синхронизации системы управления персоналом с помощью смен

Обзор

Терминология, используемая в этой статье

Перед началом работы

Предварительные условия

Знакомство с процессом интеграции

Шаг 1. Создание соединителя

Шаг 1a. Синхронизация изменений, внесенных в shifts, в систему WFM

Конечные точки

POST /connect

Пример

POST /teams/{teamid}/update

Если вы хотите настроить односторонную синхронизацию, сделайте shifts доступны только для чтения.

Пример

POST /teams/{teamid}/read

Пример: TimeOffReason

Пример: SwapRequest

Шаг 1b. Синхронизация данных из системы WFM в shifts

Начальная синхронизация

После начальной синхронизации

Шаг 2. Регистрация приложения в Центр администрирования Microsoft Entra

Шаг 3. Создание команд и расписаний для синхронизации

Шаг 4. Регистрация и включение интеграции с персоналом

Шаг 4a. Регистрация интеграции рабочей силы в клиенте

Шаг 4b. Включение интеграции сотрудников для расписаний команды

Устранение неполадок

Connector

Что произойдет, если соединитель возвращает недопустимые данные в тексте ответа?

Разделы справки определить, был ли запрос изначально выполнен в сменах или в системе WFM, чтобы предотвратить бесконечный цикл?

Регистрация интеграции с персоналом

Я зарегистрировал интеграцию сотрудников и реализовал конечные точки /connect, /update и /read, но веб-перехватчик не работает.

Справочник по конечной точке

Запрос

ConnectRequest

WfiRequestContainer

WfiRequest

Для POST /teams/{teamId}/update

Для POST /teams/{teamsId}/read

WfiRequestHeader

Отклик

WfiResponseContainer

WfiResponse

WfiResponseBody

WfiResponseError

Статьи по теме

Обратная связь

Дополнительные ресурсы