Udostępnij za pośrednictwem

Tworzenie niestandardowej integracji w celu synchronizacji systemu zarządzania pracownikami z usługą Shifts

  • Artykuł
  • Dotyczy:
    Microsoft Teams, Microsoft 365 for frontline workers

Omówienie

Zintegruj rozwiązanie Shifts, aplikację do zarządzania harmonogramem w usłudze Microsoft Teams, z systemem zarządzania pracownikami (WFM). Ta integracja umożliwia pracownikom pierwszej linii wyświetlanie harmonogramów i zarządzanie nimi bezpośrednio w ramach usługi Shifts.

W tym artykule przedstawiono sposób tworzenia łącznika przy użyciu interfejs Graph API firmy Microsoft w celu ułatwienia tej integracji.

Integrację można skonfigurować na potrzeby jednokierunkowej synchronizacji danych lub dwukierunkowej synchronizacji danych.

  • Synchronizacja jednokierunkowa (WFM system do przesunięć): w tej konfiguracji dane harmonogramu w systemie WFM są synchronizowane z usługą Shifts. Łącznik odczytuje dane w systemie WFM i zapisuje je w usłudze Shifts. Jednak wszelkie zmiany wprowadzone w zmianach przez użytkowników nie zostaną ponownie odzwierciedlone w systemie WFM.

  • Synchronizacja dwukierunkowa (system WFM i zmiany): ta konfiguracja umożliwia synchronizację dwukierunkową. Dane harmonogramu w systemie WFM są synchronizowane z zmianami, a wszelkie zmiany wprowadzone w zmianach przez użytkowników są synchronizowane z systemem WFM. Łącznik weryfikuje i zatwierdza zmiany wprowadzone przez użytkowników w usłudze Shifts zgodnie z regułami biznesowymi wymuszonymi przez system WFM przed zapisaniem zmian w usłudze Shifts.

Uwaga

Jeśli używasz WFM UKG Pro, Blue Yonder WFM lub Reflexis WFM, możesz również użyć zarządzanego łącznika do integracji usługi Shifts z systemem WFM. Aby dowiedzieć się więcej, zobacz Shifts connectors (Łączniki shifts).

Terminologia używana w tym artykule

Okres Opis
złącze Aplikacja, która synchronizuje dane harmonogramu między systemem WFM i zmianami.
integracja pracowników Jednostka definiująca metodę szyfrowania komunikacji, adres URL wywołania zwrotnego łącznika i jednostki Shifts do zsynchronizowania.

Przed rozpoczęciem

Wymagania wstępne

  • Określ, jakie dane chcesz zsynchronizować zgodnie z potrzebami biznesowymi.
  • Omówienie pojęć dotyczących uwierzytelniania i autoryzacji w Platforma tożsamości Microsoft. Zobacz Podstawy uwierzytelniania i autoryzacji.
  • wymagane role Administracja:
    • Co najmniej administrator aplikacji w chmurze, aby zarejestrować aplikację w centrum administracyjne Microsoft Entra
    • Administrator globalny do rejestrowania integracji pracowników

Zapoznaj się z procesem integracji

Oto omówienie kroków integracji. Przejrzyj te informacje, aby zrozumieć ogólny proces, w tym o tym, kto wykonuje każdy krok.

Krok Synchronizacja jednokierunkowa Synchronizacja dwukierunkowa Kto wykonuje ten krok
1 Utwórz łącznik: Utwórz łącznik: Developer
2 Rejestrowanie aplikacji w centrum administracyjne Microsoft Entra Rejestrowanie aplikacji w centrum administracyjne Microsoft Entra Konto, które jest co najmniej administratorem aplikacji w chmurze
3 Tworzenie zespołów i harmonogramów synchronizacji Tworzenie zespołów i harmonogramów synchronizacji Administrator aplikacji Developer lub Teams
4 Rejestrowanie i włączanie integracji pracowników: Rejestrowanie i włączanie integracji pracowników: Krok 4a: Administrator globalny
Krok 4b: Deweloper

Krok 1. Tworzenie łącznika

Aby utworzyć łącznik, wykonaj następujące kroki:

Krok 1a. Synchronizowanie zmian wprowadzonych w systemie WFM

Aby skonfigurować łącznik do odbierania i przetwarzania żądań z usługi Shifts, należy zaimplementować następujące punkty końcowe:

Określanie podstawowego adresu URL i adresów URL punktu końcowego

Podstawowy adres URL (element webhook) to {url}/v{apiVersion}, gdzie adres URL i apiVersion są właściwościami ustawionymi w obiekcie workforceIntegration podczas rejestrowania integracji pracowników.

Ścieżki względne adresów URL punktu końcowego są następujące:

  • /połączyć: /connect
  • /aktualizacja: /teams/{teamid}/update
  • /czytać: /teams/{teamid}/read

Jeśli na przykład adres URL to https://contosoconnector.com/wfi, a wartość apiVersion to 1:

  • Podstawowy adres URL to https://contosoconnector/com/wfi/v1.
  • Punkt końcowy /connect to https://contosoconnector/wfi/v1/connect.
  • Punkt końcowy /update to https://contosoconnector/wfi/v1/teams/{teamid}/update.
  • Punkt końcowy /read to https://contosoconnector/wfi/v1/teams/{teamid}/read.

Szyfrowanie

Wszystkie żądania są szyfrowane przy użyciu AES-256-CBC-HMAC-SHA256. Wspólny klucz tajny należy określić podczas rejestrowania integracji pracowników. Odpowiedzi wysyłane z powrotem do usługi Shifts nie powinny być szyfrowane.

Punkty końcowe

POST /connect

Funkcja Shifts wywołuje ten punkt końcowy, aby przetestować połączenie podczas rejestrowania integracji pracowników. Odpowiedź powodzenie jest zwracana tylko wtedy, gdy ten punkt końcowy zwraca odpowiedź HTTP 200 OK .

Przykład

Prosić
ConnectRequest

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

Odpowiedź
Zwracanie protokołu HTTP 200 OK

POST /teams/{teamid}/update

Funkcja Shifts wywołuje ten punkt końcowy w celu uzyskania zatwierdzenia po wprowadzeniu zmiany w jednostce Shifts zgodnie z harmonogramem , który jest włączony dla integracji pracowników. Jeśli ten punkt końcowy zatwierdzi żądanie, zmiana zostanie zapisana w obszarze Zmiany.

Ponieważ system WFM jest systemem rekordów, łącznik odbiera żądanie do tego punktu końcowego, powinien najpierw podjąć próbę wprowadzenia zmiany w systemie WFM. Jeśli zmiana zakończy się pomyślnie, zwróć powodzenie. W przeciwnym razie zwraca błąd.

Funkcja Shifts wywołuje ten punkt końcowy dla każdej zmiany (w tym zmian zainicjowanych z systemu łącznika/WFM). Jeśli łącznik wysłał aktualizację do usługi Shifts przy użyciu interfejs Graph API i dodał X-MS-WFMPassthrough: workforceIntegratonId nagłówek, żądanie przychodzące do tego punktu końcowego będzie miało ten sam nagłówek, co pozwala odpowiednio identyfikować i obsługiwać te żądania. Na przykład powrót powodzenie bez wprowadzania tej samej zmiany w systemie WFM, jak byłoby nadmiarowe i może spowodować, że łącznik utknie w nieskończonej pętli.

Na poniższym diagramie przedstawiono przepływ danych.

Diagram przedstawiający przepływ aktualizacji z przejścia do systemu WFM.

Uwaga

Aby uzyskać więcej informacji na temat modeli żądań i odpowiedzi, zobacz WfiRequest w sekcji dokumentacji punktu końcowego w tym artykule.

Zwracanie kodu odpowiedzi
Każda odpowiedź z integracji, w tym błąd, musi mieć kod 200 OKodpowiedzi HTTP . Treść odpowiedzi musi mieć stan i komunikat o błędzie, który odzwierciedla odpowiedni stan błędu wywołania podrzędnego. Każda odpowiedź z integracji innej niż 200 OK jest traktowana jako błąd i zwracana do obiektu wywołującego (klienta lub programu Microsoft Graph).

Jeśli chcesz skonfigurować synchronizację jednokierunkową, ustaw opcję Shifts tylko do odczytu

W przypadku synchronizacji jednokierunkowej należy wprowadzić zmiany tylko do odczytu, aby użytkownicy nie mogli wprowadzać zmian w zmianach. Aby przesunięcia były tylko do odczytu, zwróć odpowiedź na błąd dla wszystkich żądań z usługi Shifts.

Aby na przykład zablokować użytkownikom możliwość wprowadzania zmian w harmonogramie, ten punkt końcowy musi zwrócić odpowiedź na błąd za każdym razem, gdy otrzyma żądanie dotyczące shift jednostki.

Przykład

Prosić
WfiRequestContainer

W poniższym przykładzie przedstawiono żądanie z usługi Shifts z pytaniem, czy przesunięcie, którego identyfikator to SHFT_12345678-1234-1234-12334-1234567890ab i ma właściwości wymienione w treści, można zapisać w usłudze Shifts. To żądanie zostało wyzwolone, gdy użytkownik utworzy zmianę w usłudze 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"
      }
    }
  ]
}

Odpowiedź
WfiResponse

Powodzenie: zwracanie protokołu HTTP 200 OK

W tym przykładzie przedstawiono odpowiedź zwróconą, jeśli punkt końcowy zatwierdził żądanie. W tym scenariuszu zmiana jest zapisywana w obszarze Zmiany, a użytkownik może zobaczyć zmianę w harmonogramie.

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

Błąd: zwracany protokół HTTP 200 OK

W tym przykładzie przedstawiono odpowiedź zwróconą, jeśli punkt końcowy odrzucił żądanie. W tym scenariuszu użytkownik otrzymuje komunikat o błędzie "Nie można dodać zmiany" w obszarze Zmiany.

{
    "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

Ten punkt końcowy obsługuje żądania ze zmian w celu pobrania kwalifikujących się przyczyn limitu czasu lub kwalifikujących się zmian dla żądań zamiany dla użytkownika.

Uwaga

Od października 2024 r. ten punkt końcowy jest obsługiwany tylko w wersji beta programu Microsoft interfejs Graph API. Należy również określić wartości właściwości eligibilityFilteringEnabledEntities podczas rejestrowania integracji pracowników.

Na poniższym diagramie przedstawiono przepływ danych.

Diagram przedstawiający przepływ żądań filtrowania uprawnień.

Zwracanie kodu odpowiedzi
Każda odpowiedź z integracji, w tym błąd, musi mieć kod 200 OKodpowiedzi HTTP . Treść odpowiedzi musi zawierać stan i komunikat o błędzie, który odzwierciedla odpowiedni stan błędu wywołania podrzędnego. Każda odpowiedź z integracji innej niż 200 OK jest traktowana jako błąd i zwracana do obiektu wywołującego (klienta lub programu Microsoft Graph).

Przykład: TimeOffReason

Prosić

W poniższym przykładzie przedstawiono żądanie z usługi Shifts z pytaniem, do którego czasu wolnego jest uprawniony użytkownik (identyfikator użytkownika aa162a04-bec6-4b81-ba99-96caa7b2b24d). To żądanie zostało wyzwolone, gdy użytkownik zażąda czasu wolnego w funkcji Shifts.

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

Odpowiedź
Powodzenie: zwracanie protokołu HTTP 200 OK

Poniższa odpowiedź pokazuje, że identyfikatory przyczyny kwalifikującego się czasu wolnego dla użytkownika to "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" i "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". W tym scenariuszu użytkownik widzi odpowiednie przyczyny limitu czasu do wyboru w obszarze Shifts.

{
    "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 
          } 
        }
    ]
}

Błąd: zwracany protokół HTTP 200 OK

W tym przykładzie zwracana jest odpowiedź o błędzie, ponieważ łącznik nie może nawiązać połączenia z systemem WFM w celu pobrania przyczyny wolnego czasu dla użytkownika.

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

Prosić

W poniższym przykładzie przedstawiono żądanie z usługi Shifts z pytaniem, które zmiany kwalifikują się do zamiany ze zmianą o identyfikatorze SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 w latach 2024-2024 10-01T04:00:00.000000Z i 2024-11-01T03:59:59.999000Z.

{
  "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"
    }
  ]
}

Odpowiedź
Powodzenie: zwracanie protokołu HTTP 200 OK

Poniższa odpowiedź pokazuje, że zmianę można zamienić na zmianę, której identyfikator to 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, 
      } 
    }
  ]
}

Błąd: zwracany protokół HTTP 200 OK

W tym przykładzie zwracana jest odpowiedź o błędzie, ponieważ łącznik nie może nawiązać połączenia z systemem WFM w celu pobrania kwalifikujących się zmian dla żądania zamiany dla użytkownika.

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

Krok 1b. Synchronizowanie danych z systemu WFM do zmian

Użyj interfejsów API shifts w programie Microsoft Graph, aby odczytywać dane harmonogramu z systemu WFM i zapisywać dane w usłudze Shifts.

Aby na przykład dodać zmianę do funkcji Shifts, użyj interfejsu API tworzenia przesunięcia .

Zobacz dokumentację usługi Microsoft interfejs Graph API w wersji 1.0 dla interfejsów API usługi Shifts, które są wymienione w obszarze Zarządzanie zmianami.

Uwaga

Nagłówek MS-APP-ACTS-AS jest wymagany w żądaniach i musi zawierać identyfikator (GUID) użytkownika działającego w imieniu aplikacji. Zalecamy użycie identyfikatora użytkownika właściciela zespołu podczas aktualizowania harmonogramu.

Na poniższym diagramie przedstawiono przepływ danych.

Diagram przedstawiający przepływ synchronizacji danych z systemu WFM do przesunięć.

Synchronizacja początkowa

W przypadku pierwszej synchronizacji łącznik powinien odczytywać dane w systemie WFM i zapisywać dane w usłudze Shifts. Zalecamy zsynchronizowanie dwóch tygodni przyszłych danych.

Po początkowej synchronizacji

Po pierwszej synchronizacji możesz wybrać następujące opcje:

  • Synchronicznie aktualizuj zmiany ze zmianami w systemie WFM: wyślij aktualizację do usługi Shifts dla każdej zmiany wprowadzonej w systemie WFM.

  • Asynchronicznie zaktualizuj zmiany w systemie WFM: wykonaj okresową synchronizację, zapisując wszystkie zmiany, które wystąpiły w systemie WFM w określonym przedziale czasu (na przykład 10 minut) na zmiany.

    Wszystkie operacje zapisu w usłudze Shifts, w tym operacje zapisu zainicjowane przez łącznik, wyzwalają wywołanie /update punktu końcowego łącznika. Zalecamy uwzględnienie nagłówka X-MS-WFMPassthrough: workforceIntegratonId do wszystkich wywołań zapisu, aby łącznik mógł je odpowiednio zidentyfikować i obsłużyć. Jeśli na przykład system WFM zainicjował zmianę, zatwierdź ją bez stosowania aktualizacji do systemu WFM.

    Uwaga

    Jeśli konfigurujesz łącznik na potrzeby dwukierunkowej synchronizacji danych między systemem WFM i zmianami, wyklucz zmiany inicjowane z funkcji Shift w ramach synchronizacji okresowej. Te zmiany są już napisane w obszarze Shifts.

Krok 2. Rejestrowanie aplikacji w centrum administracyjne Microsoft Entra

Wykonaj następujące kroki, aby zarejestrować aplikację dla łącznika w Platforma tożsamości Microsoft, skonfigurować uprawnienia aplikacji do uzyskiwania dostępu do programu Microsoft Graph i uzyskać token dostępu.

  1. Zaloguj się do centrum administracyjne Microsoft Entra co najmniej jako administrator aplikacji w chmurze.

  2. Zarejestruj swoją aplikację. Aby uzyskać instrukcje, zobacz Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

  3. Przypisz uprawnienia aplikacjiSchedule.ReadWrite.All do aplikacji w celu uzyskania dostępu tylko do aplikacji i uzyskania tokenu dostępu.

    Aby uzyskać szczegółowe wskazówki, zobacz Uzyskiwanie dostępu bez użytkownika.

    Token dostępu sprawdza, czy aplikacja jest autoryzowana do wywoływania programu Microsoft Graph przy użyciu własnej tożsamości przy użyciu uprawnienia Schedule.ReadWrite.All . Musi zostać uwzględniony w nagłówku autoryzacji żądań.

Krok 3. Tworzenie zespołów i harmonogramów synchronizacji

Skonfiguruj zespoły w usłudze Teams, które chcesz zsynchronizować. Możesz użyć istniejących zespołów lub utworzyć nowe zespoły.

  1. Skonfiguruj zespoły w usłudze Teams, aby odpowiadać zespołom i lokalizacjom w systemie WFM. Upewnij się, że do każdego zespołu zostały dodane następujące osoby:

    • Menedżerowie linii frontu jako właściciele zespołów. Upewnij się, że dodasz użytkownika w nagłówku MS-APP-ACTS-AS jako właściciela zespołu każdego odpowiedniego zespołu.
    • Pracownicy pierwszej linii jako członkowie zespołu.

  2. Utwórz harmonogram w obszarze Zmiany dla każdego zespołu. Aby dowiedzieć się więcej, zobacz Tworzenie lub zastępowanie harmonogramu.

  3. Dodaj grupy harmonogramów do harmonogramu dla każdego zespołu. Grupy harmonogramów służą do grupowania pracowników na podstawie typowych cech w zespole. Na przykład grupy harmonogramów mogą być działami lub typami zadań. Aby dowiedzieć się więcej, zobacz schedulingGroup resource type (Typ zasobu schedulingGroup).

  4. Dodaj pracowników do każdej grupy harmonogramów. Aby dowiedzieć się więcej, zobacz Zastępowanie grupy planowania.

Uwaga

Możesz również użyć centrum administracyjnego usługi Teams, aby skonfigurować swoje zespoły i wdrożyć zmiany w zespołach. Aby dowiedzieć się więcej, zobacz:

Krok 4. Rejestrowanie i włączanie integracji pracowników

Integracja pracowników definiuje ustawienia szyfrowania komunikacji między funkcjami Shifts i łącznikiem, adres URL wywołań zwrotnych z usługi Shifts oraz typy jednostek do zsynchronizowania.

Aby zarejestrować i włączyć integrację pracowników, wykonaj następujące kroki:

Krok 4a. Rejestrowanie integracji pracowników w dzierżawie

Aby wykonać ten krok, musisz być administratorem globalnym.

Użyj interfejsu API Tworzenia pracownikówIntegration , aby zarejestrować integrację pracowników w dzierżawie.

Oto przykład żądania.

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”,
}

Aby uzyskać szczegółowe informacje, zobacz poniższą tabelę. Aby dowiedzieć się więcej, zobacz workforceIntegration resource type (Typ zasobu workforceIntegration).

Własność Więcej informacji
apiVersion Wersja interfejsu API dla adresu URL wywołania zwrotnego. Podstawowy adres URL składa się z właściwości url i tej właściwości.
szyfrowanie Ustaw protokół na sharedSecretwartość . Wartość wpisu tajnego musi zawierać dokładnie 64 znaki.

Użyj wpisu tajnego, aby odszyfrować zaszyfrowane ładunki JSON wysyłane do punktu końcowego łącznika z usługi Shifts. Ładunek jest szyfrowany przy użyciu AES-256-CBC-HMAC-SHA256. Aplikacja powinna bezpiecznie utrwalić ten wpis tajny. Na przykład w magazynie kluczy.
supportedEntities Określ jednostki Shifts, które mają być obsługiwane przez łącznik na potrzeby synchronizacji. Funkcja Shifts wywołuje punkt końcowy /update łącznika, gdy dowolna z tych jednostek zmieni się, aby można było zatwierdzić lub odrzucić zmianę. Aby uzyskać listę możliwych wartości, zobacz workforceIntegration resource type (Typ zasobu workforceIntegration)

Nuta Ta lista jest rozwijanym wyliczeniem. Aby uzyskać wszystkie wartości, Prefer: include-unknown-enum-members należy użyć nagłówka żądania.
eligibilityFilteringEnabledEntities Uwaga: od października 2024 r. ten punkt końcowy jest obsługiwany tylko w wersji beta programu Microsoft interfejs Graph API.

Określ jednostki shifts, które chcesz połączyć, aby obsługiwać filtrowanie uprawnień. Możliwe wartości to:
  • none: Pusta lista
  • SwapRequests: Funkcja Shift wywołuje punkt końcowy /read łącznika, aby uzyskać filtrowaną listę zmian, z których użytkownik może wybrać żądanie zamiany.
  • TimeOffReasons: Shifts wywołuje / read punktu końcowego łącznika, aby uzyskać odfiltrowaną listę powodów, dla których użytkownik może wybrać, gdy żąda czasu wolnego.
Nuta Ta lista jest rozwijanym wyliczeniem. Aby uzyskać wszystkie wartości, Prefer: include-unknown-enum-members należy użyć nagłówka żądania.
adres URL Adres URL integracji pracowników dla wywołań zwrotnych z usługi Shifts. Podstawowy adres URL składa się z tej właściwości i właściwości apiVerson.

Krok 4b. Włączanie integracji pracowników dla harmonogramów zespołu

Włącz integrację pracowników zgodnie z harmonogramami, które chcesz zarządzać. W tym celu użyj interfejsu API tworzenia lub zastępowania harmonogramu , aby utworzyć lub zaktualizować harmonogram dla zespołów.

Oto przykład żądania.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}
  • Określ workforceIntegrationId, który został wygenerowany podczas rejestrowania integracji pracowników.
  • Można włączyć maksymalnie jedną integrację pracowników w harmonogramie. Jeśli uwzględnisz w żądaniu więcej niż jednego pracownikaIntegrationId, zostanie użyty pierwszy z nich.

Rozwiązywanie problemów

Złącze

Jeśli łącznik odpowiada na żądanie z usługi Shifts, co się stanie, jeśli zwróci kod odpowiedzi inny niż 200? Czy ma to znaczenie, jeśli zwraca stan inny niż 200 w treści odpowiedzi?

Istnieje różnica między tymi dwoma scenariuszami.

  • Jeśli łącznik zwraca kod odpowiedzi inny niż 200, shifts próbuje ponowić próbę /read i /update punktów końcowych wiele razy. Ostatecznie shifts wyświetla komunikat "Coś poszło nie tak. Konfiguracja integracji pracowników w zespole odpowiedziała nieprawidłowymi danymi". Komunikat o błędzie.
  • Jeśli łącznik zwraca stan inny niż 200 w treści odpowiedzi, funkcja Shifts wyświetli komunikat "Wystąpił problem. Niestety, nie można ukończyć zmiany", komunikat o błędzie i przestaje ponawiać próby punktów końcowych.

Co się stanie, jeśli łącznik zwróci nieprawidłowe dane w treści odpowiedzi?

Shifts próbuje ponowić próbę /read i /update punktów końcowych wiele razy. Ostatecznie shifts wyświetla komunikat "Coś poszło nie tak. Integracja pracowników skonfigurowana w twoim zespole odpowiedziała nieprawidłowymi danymi" — komunikat o błędzie.

Jak mogę określić, czy żądanie zostało pierwotnie wykonane w systemie Shifts, czy w systemie WFM, aby zapobiec nieskończonej pętli?

Dodaj nagłówek X-MS-WFMPassthrough: workforceIntegratonId do wszystkich wywołań zapisu i aktualizacji, aby zidentyfikować/zignorować zmiany wyzwalane przez łącznik. Ten nagłówek służy do wskazywania, że żądanie zostało wykonane z powodu poprzedniego wywołania, które zostało wykonane przez łącznik w celu interfejs Graph API synchronizowania danych z systemu WFM z funkcją Shifts.

Rejestracja integracji pracowników

Zarejestrowano integrację pracowników i określono "eligibilityFilteringEnabledEntities", w tym "SwapRequest, OfferShiftRequest i TimeOffReason", ale treść odpowiedzi nie pokazuje listy "eligibilityFilteringEnabledEntities".

Filtrowanie uprawnień jest obecnie obsługiwane za pośrednictwem https://graph.microsoft.com/beta punktu końcowego, a https://graph.microsoft.com/v1 nie punktu końcowego.

Zarejestrowano integrację pracowników i dodano "supportedEntities", ale otrzymano odpowiedź 400 Nieprawidłowe żądanie i "Nieprawidłowy ładunek: Żądana wartość 'shift, ....' nie odnaleziono".

Upewnij się, że każda jednostka Shifts w supportedEntities treści żądania listy zaczyna się wielką literą. Na przykład "supportedEntities":"Shift,SwapRequest,OpenShift".

Zarejestrowano integrację pracowników i zaimplementowano punkty końcowe /connect, /update i /read, ale element webhook nie działa.

Upewnij się, że integracja pracowników jest włączona dla harmonogramu zespołu. Ponadto sprawdź, czy właściwości url i apiVersion są poprawne.

Dokumentacja punktu końcowego

Prosić

ConnectRequest

Własność Wpisać Opis
tenantId Ciąg Identyfikator dzierżawy na potrzeby integracji pracowników
userId Ciąg Identyfikator użytkownika na potrzeby integracji pracowników 
{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Własność Wpisać Opis
Żądania Kolekcja WfiRequest Lista WfiRequests 
{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

Liczba elementów żądania:

  • W większości przypadków żądanie ma jeden element.
  • Niektóre żądania, takie jak zamiana zatwierdzeń żądań zmiany, mają pięć elementów: jedno żądanie zamiany PUT, dwie zmiany DELETE (istniejące zmiany) i dwie zmiany POST (nowe zmiany).

WfiRequest

Własność Wpisać Opis
id Ciąg Identyfikator jednostki
metoda Ciąg Metoda wywoływana w elemencie. Na przykład , POST, PUT, GET, DELETE.
adres URL Ciąg Wskazuje typ jednostki i szczegóły operacji.
Nagłówki WfiRequestHeader Nagłówki
ciało ShiftsEntity Treść jednostki powiązanej z żądaniem.
Dla POST /teams/{teamId}/update
Własność Wpisać Opis
id Ciąg Identyfikator jednostki
metoda Ciąg POST aby utworzyć jednostkę, PUT zaktualizować jednostkę, DELETE usunąć jednostkę.
adres URL Ciąg Format to /{EntityType}/{EntityId}. Możliwe wartości dla to , , , , , openshiftrequests, offershiftrequests, timesoff, . timeOffRequestsopenshiftstimeoffReasonsswapRequestsshifts{EntityType} Na przykład /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
nagłówek WfiRequestHeader Nagłówek
ciało ShiftsEntity Musi być zgodna {EntityType} z właściwością adresu URL . Użyj jednej z opcji shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Na przykład /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
W przypadku postu /teams/{teamsId}/read
Własność Wpisać Opis
id Ciąg Identyfikator jednostki
metoda Ciąg Jest zawsze GET.
adres URL Ciąg
  • TimeOffReasons: format to /users/{userId}/timeOffReasons?requestType=TimeOffReason. Na przykład /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason.
  • SwapRequest: format to /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Na przykład shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
nagłówek WfiRequestHeader Nagłówek
ciało ShiftsEntity Jest zawsze null.

WfiRequestHeader

Własność Wpisać Opis
X-MS-Transaction-ID Ciąg Identyfikator transakcji
X-MS-Expires Ciąg (DateTime) Data/godzina wygaśnięcia transakcji

X-MS-WFMPassthrough: workforceIntegratonId nie zostanie uwzględniony w WfiRequestHeader. Powinien zostać wyodrębniony z protokołu HttpRequest.

Odpowiedź

WfiResponseContainer

Własność Wpisać Opis
Odpowiedzi Kolekcja WfiResponse Lista WfiResponses 
{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Własność Wpisać Opis
id Ciąg Identyfikator jednostki
stan Ciąg Wynik operacji
ciało WfiResponseBody WfiResponseBody

WfiResponseBody

Własność Wpisać Opis
eTag Ciąg eTag
błąd WfiResponseError Szczegóły dotyczące błędu
dane Ciąg Żądane dane (dla żądań odczytu)

WfiResponseError

Własność Wpisać Opis
kod Ciąg Kod błędu
wiadomości Ciąg Komunikat o błędzie