Freigeben über

Erstellen einer benutzerdefinierten Integration zum Synchronisieren Ihres Personalverwaltungssystems mit Schichten

  • Artikel
  • Gilt für::
    Microsoft Teams, Microsoft 365 for frontline workers

Übersicht

Integrieren Sie Schichten, die Planverwaltungs-App in Microsoft Teams, in Ihr Personalverwaltungssystem (WFM). Diese Integration ermöglicht es Ihren Mitarbeitern in Service und Produktion, ihre Zeitpläne direkt in Schichten anzuzeigen und zu verwalten.

In diesem Artikel erfahren Sie, wie Sie mithilfe des Microsoft-Graph-API einen Connector erstellen, um diese Integration zu erleichtern.

Sie können Ihre Integration für eine unidirektionale Datensynchronisierung oder eine bidirektionale Datensynchronisierung einrichten.

  • Unidirektionale Synchronisierung (WFM System mit Schichten): Bei diesem Setup werden Die Daten in Ihrem WFM System mit Schichten synchronisiert. Der Connector liest die Daten in Ihrem WFM System und schreibt sie in Schichten. Änderungen, die von Benutzern in Schichten vorgenommen werden, werden jedoch nicht in Ihrem WFM-System widerspiegelt.

  • Bidirektionale Synchronisierung (WFM System und Schichten): Dieses Setup ermöglicht eine bidirektionale Synchronisierung. Zeitplandaten in Ihrem WFM System werden mit Schichten synchronisiert, und alle Änderungen, die von Benutzern an Schichten vorgenommen werden, werden wieder mit Ihrem WFM System synchronisiert. Der Connector überprüft und genehmigt die Änderungen, die Benutzer in Schichten gemäß den von Ihrem WFM System erzwungenen Geschäftsregeln vornehmen, bevor die Änderungen in Schichten geschrieben werden.

Hinweis

Wenn Sie UKG Pro WFM, Blue Yonder WFM oder Reflexis WFM verwenden, können Sie auch einen verwalteten Connector verwenden, um Schichten in Ihr WFM-System zu integrieren. Weitere Informationen finden Sie unter Schichten von Connectors.

In diesem Artikel verwendete Terminologie

Ausdruck Beschreibung
Verbinder Eine App, die Zeitplandaten zwischen Ihrem WFM System und Schichten synchronisiert.
Personalintegration Eine Entität, die die Verschlüsselungsmethode für die Kommunikation, die Rückruf-URL für Ihren Connector und die zu synchronisierenden Schichten-Entitäten definiert.

Bevor Sie beginnen

Voraussetzungen

  • Bestimmen Sie, welche Daten Sie gemäß Ihren geschäftlichen Anforderungen synchronisieren möchten.
  • Machen Sie sich mit den Authentifizierungs- und Autorisierungskonzepten im Microsoft Identity Platform vertraut. Weitere Informationen finden Sie unter Grundlagen zu Authentifizierung und Autorisierung.
  • Admin erforderlichen Rollen:
    • Mindestens ein Cloudanwendungsadministrator, um eine App im Microsoft Entra Admin Center
    • Globaler Administrator zum Registrieren der Mitarbeiterintegration

Machen Sie sich mit dem Integrationsprozess vertraut

Hier finden Sie eine Übersicht über die Integrationsschritte. Überprüfen Sie diese Informationen, um einen Überblick über den gesamten Prozess zu erhalten, einschließlich der Person, die die einzelnen Schritte ausführt.

Schritt Unidirektionale Synchronisierung Bidirektionale Synchronisierung Wer diesen Schritt ausführt
1 Erstellen Sie Ihren Connector: Erstellen Sie Ihren Connector: Developer
2 Registrieren einer App im Microsoft Entra Admin Center Registrieren einer App im Microsoft Entra Admin Center Ein Konto, das mindestens ein Cloudanwendungsadministrator ist
3 Erstellen von Teams und Zeitplänen für die Synchronisierung Erstellen von Teams und Zeitplänen für die Synchronisierung Entwickler oder Teams-Administrator
4 Registrieren und Aktivieren der Integration von Mitarbeitern: Registrieren und Aktivieren der Integration von Mitarbeitern: Schritt 4a: Globaler Administrator
Schritt 4b: Entwickler

Schritt 1: Erstellen Des Connectors

Führen Sie zum Erstellen Ihres Connectors die folgenden Schritte aus:

Schritt 1a: Synchronisieren von Änderungen, die in Schichten vorgenommen wurden, mit Ihrem WFM System

Um Ihren Connector für den Empfang und die Verarbeitung von Anforderungen von Schichten einzurichten, müssen Sie die folgenden Endpunkte implementieren:

Ermitteln Der Basis-URL und der Endpunkt-URLs

Die Basis-URL (Webhook) ist {url}/v{apiVersion}, wobei url und apiVersion die Eigenschaften sind, die Sie im workforceIntegration-Objekt festlegen, wenn Sie die Personalintegration registrieren.

Die relativen Pfade der Endpunkt-URLs sind wie folgt:

  • /verbinden: /connect
  • /aktualisieren: /teams/{teamid}/update
  • /lesen: /teams/{teamid}/read

Beispiel: Wenn url ist https://contosoconnector.com/wfi und apiVersion ist 1:

  • Die Basis-URL lautet https://contosoconnector/com/wfi/v1.
  • Der /connect-Endpunkt ist https://contosoconnector/wfi/v1/connect.
  • Der /update-Endpunkt ist https://contosoconnector/wfi/v1/teams/{teamid}/update.
  • Der /read-Endpunkt ist https://contosoconnector/wfi/v1/teams/{teamid}/read.

Verschlüsselung

Alle Anforderungen werden mit AES-256-CBC-HMAC-SHA256 verschlüsselt. Sie geben den gemeinsam verwendeten geheimen Schlüssel an, wenn Sie die Personalintegration registrieren. An Schichten zurückgesendete Antworten sollten nicht verschlüsselt werden.

Endpunkte

POST /connect

Shifts ruft diesen Endpunkt auf, um die Verbindung zu testen, wenn Sie die Mitarbeiterintegration registrieren. Eine Erfolgsantwort wird nur zurückgegeben, wenn dieser Endpunkt eine HTTP-Antwort 200 OK zurückgibt.

Beispiel

Anforderung
ConnectRequest

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

Antwort
Http zurückgeben 200 OK

POST /teams/{teamid}/update

Schichten ruft diesen Endpunkt auf, um eine Genehmigung zu erhalten, wenn eine Änderung an einer Schichtentität in einem Zeitplan vorgenommen wird, der für die Integration der Mitarbeiter aktiviert ist. Wenn dieser Endpunkt die Anforderung genehmigt, wird die Änderung in Schichten gespeichert.

Da ihr WFM System der Aufzeichnung ist, sollte der Connector, wenn er eine Anforderung an diesen Endpunkt empfängt, zuerst versuchen, die Änderung im WFM System vorzunehmen. Wenn die Änderung erfolgreich ist, wird der Erfolg zurückgegeben. Andernfalls wird ein Fehler zurückgegeben.

Shifts ruft diesen Endpunkt für jede Änderung (einschließlich änderungen, die vom Connector/WFM System initiiert wurden) auf. Wenn der Connector mithilfe von Graph-API ein Update an Shifts gesendet und den X-MS-WFMPassthrough: workforceIntegratonId Header hinzugefügt hat, weist die anforderung, die an diesen Endpunkt gesendet wird, denselben Header auf, sodass Sie diese Anforderungen identifizieren und entsprechend behandeln können. Sie können z. B. erfolgreich zurückgeben, ohne die gleiche Änderung im WFM System vorzunehmen, wie es redundant wäre und dazu führen kann, dass der Connector in einer Endlosschleife hängen bleibt.

Das folgende Diagramm zeigt den Datenfluss.

Diagramm, das den Ablauf für Updates von Schichten zu Ihrem WFM-System zeigt.

Hinweis

Weitere Informationen zu Anforderungs- und Antwortmodellen finden Sie unter WfiRequest im Abschnitt Endpunktreferenz dieses Artikels.

Zurückgeben des Antwortcodes
Jede Antwort der Integration, einschließlich eines Fehlers, muss über einen HTTP-Antwortcode verfügen 200 OK. Der Antworttext muss über die status und die Fehlermeldung verfügen, die den entsprechenden Fehlerzustand des Untergeordneten Aufrufs widerspiegelt. Jede andere Antwort der Integration als 200 OK wird als Fehler behandelt und an den Aufrufer (Client oder Microsoft Graph) zurückgegeben.

Wenn Sie eine unidirektionale Synchronisierung einrichten möchten, legen Sie schichten schreibgeschützt fest.

Für eine unidirektionale Synchronisierung müssen Sie Schichten schreibgeschützt machen, damit Benutzer keine Änderungen an Schichten vornehmen können. Um Schichten schreibgeschützt zu machen, geben Sie eine Fehlerantwort für alle Anforderungen von Schichten zurück.

Um beispielsweise zu verhindern, dass Benutzer Änderungen an Verschiebungen im Zeitplan vornehmen, muss dieser Endpunkt eine Fehlerantwort zurückgeben, wenn er eine Anforderung in Bezug auf eine shift Entität empfängt.

Beispiel

Anforderung
WfiRequestContainer

Das folgende Beispiel zeigt eine Anforderung von Schichten, die fragt, ob eine Schicht, deren ID SHFT_12345678-1234-1234-1234-1234-1234567890ab ist und über die im Text aufgeführten Eigenschaften verfügt, in Schichten gespeichert werden kann. Diese Anforderung wurde ausgelöst, wenn ein Benutzer eine Schicht in Schichten erstellt.

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

Antwort
WfiResponse

Erfolg: Http zurückgeben 200 OK

Dieses Beispiel zeigt die Antwort, die zurückgegeben wird, wenn der Endpunkt die Anforderung genehmigt hat. In diesem Szenario wird die Schicht in Schichten gespeichert, und der Benutzer kann die Verschiebung im Zeitplan sehen.

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

Fehler: Http zurückgeben 200 OK

Dieses Beispiel zeigt die Antwort, die zurückgegeben wird, wenn der Endpunkt die Anforderung abgelehnt hat. In diesem Szenario erhält der Benutzer die Fehlermeldung "Die Verschiebung konnte nicht hinzugefügt werden" in Schichten.

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

Dieser Endpunkt verarbeitet Anforderungen von Schichten, um berechtigte Gründe für Verschiebungen oder berechtigte Schichten für Tauschanforderungen für einen Benutzer abzurufen.

Hinweis

Ab Oktober 2024 wird dieser Endpunkt nur in der Betaversion von Microsoft Graph-API unterstützt. Sie müssen auch Werte für die eigenschaft eligibilityFilteringEnabledEntities angeben, wenn Sie die Personalintegration registrieren.

Das folgende Diagramm zeigt den Datenfluss.

Diagramm, das den Ablauf für Berechtigungsfilteranforderungen zeigt.

Zurückgeben des Antwortcodes
Jede Antwort der Integration, einschließlich eines Fehlers, muss über einen HTTP-Antwortcode verfügen 200 OK. Der Antworttext muss den status und die Fehlermeldung enthalten, die den entsprechenden Fehlerzustand des Untergeordneten Aufrufs widerspiegelt. Jede andere Antwort der Integration als 200 OK wird als Fehler behandelt und an den Aufrufer (Client oder Microsoft Graph) zurückgegeben.

Beispiel: TimeOffReason

Anforderung

Das folgende Beispiel zeigt eine Anforderung von Schichten, in der gefragt wird, für welche Gründe für die Freiezeit ein Benutzer (Benutzer-ID aa162a04-bec6-4b81-ba99-96caa7b2b24d) berechtigt ist. Diese Anforderung wurde ausgelöst, wenn der Benutzer freizeit in Schichten anfordert.

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

Antwort
Erfolg: Http zurückgeben 200 OK

Die folgende Antwort zeigt, dass die zulässigen Gründe für die Sperre für den Benutzer "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" und "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d" sind. In diesem Szenario sieht der Benutzer die entsprechenden Gründe für die Auszeit in Schichten.

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

Fehler: Http zurückgeben 200 OK

In diesem Beispiel wird eine Fehlerantwort zurückgegeben, da der Connector das WFM System nicht erreichen konnte, um die Gründe für die Nichtzeit für den Benutzer abzurufen.

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

Anforderung

Das folgende Beispiel zeigt eine Anforderung von Schichten, die fragt, welche Schichten für einen Austausch mit der Schicht geeignet sind, deren ID SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 zwischen 2024-2029 ist.10-01T04:00:00.0000000Z und 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"
    }
  ]
}

Antwort
Erfolg: Http zurückgeben 200 OK

Die folgende Antwort zeigt, dass die Schicht mit der Schicht getauscht werden kann, deren ID SHFT_98e96e23-966b-43be-b90d-4697037b67af lautet.

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

Fehler: Http zurückgeben 200 OK

In diesem Beispiel wird eine Fehlerantwort zurückgegeben, da der Connector das WFM System nicht erreichen konnte, um berechtigte Schichten für eine Auslagerungsanforderung für den Benutzer abzurufen.

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

Schritt 1b: Synchronisieren von Daten aus Ihrem WFM System mit Schichten

Verwenden Sie Schichten-APIs in Microsoft Graph, um Zeitplandaten aus Ihrem WFM System zu lesen und die Daten in Schichten zu schreiben.

Wenn Sie beispielsweise eine Verschiebung zu Schichten hinzufügen möchten, verwenden Sie die API Zum Erstellen von Schichten .

Weitere Informationen finden Sie in der Referenz zu Microsoft Graph-API v1.0 für Schichten-APIs, die unter Schichtverwaltung aufgeführt sind.

Hinweis

Der MS-APP-ACTS-AS Header ist in Anforderungen erforderlich und muss die ID (GUID) des Benutzers enthalten, für den Ihre App fungiert. Es wird empfohlen, beim Aktualisieren des Zeitplans die Benutzer-ID eines Teambesitzers zu verwenden.

Das folgende Diagramm zeigt den Datenfluss.

Diagramm, das den Fluss zum Synchronisieren von Daten aus Ihrem WFM-System mit Schichten zeigt.

Erste Synchronisierung

Für die erste Synchronisierung sollte der Connector Daten in Ihrem WFM System lesen und die Daten in Schichten schreiben. Es wird empfohlen, zukünftige Daten für zwei Wochen zu synchronisieren.

Nach der ersten Synchronisierung

Nach der ersten Synchronisierung können Sie Folgendes auswählen:

  • Synchrones Aktualisieren von Schichten mit Änderungen in Ihrem WFM System: Senden Sie für jede In Ihrem WFM System vorgenommene Änderung ein Update an Schichten.

  • Asynchrones Aktualisieren von Schichten mit Änderungen in Ihrem WFM System: Führen Sie eine regelmäßige Synchronisierung durch, indem Sie alle Änderungen, die innerhalb eines bestimmten Zeitrahmens (z. B. 10 Minuten) in Ihrem WFM System aufgetreten sind, in Schichten schreiben.

    Alle Schreibvorgänge in Schichten, einschließlich schreibvorgängen, die vom Connector initiiert wurden, lösen einen Aufruf des /update-Endpunkts des Connectors aus. Es wird empfohlen, den X-MS-WFMPassthrough: workforceIntegratonId Header für alle Schreibaufrufe einzuschließen, damit der Connector sie identifizieren und entsprechend behandeln kann. Wenn Ihr WFM System die Änderung beispielsweise initiiert hat, genehmigen Sie sie, ohne ein Update auf Ihr WFM System anzuwenden.

    Hinweis

    Wenn Sie Ihren Connector für eine bidirektionale Synchronisierung von Daten zwischen Ihrem WFM System und Schichten einrichten, schließen Sie Änderungen aus, die von Schichten in der regelmäßigen Synchronisierung initiiert wurden. Diese Änderungen sind bereits in Schichten geschrieben.

Schritt 2: Registrieren einer App im Microsoft Entra Admin Center

Führen Sie die folgenden Schritte aus, um eine App für Ihren Connector im Microsoft Identity Platform zu registrieren, berechtigungen für die App für den Zugriff auf Microsoft Graph zu konfigurieren und ein Zugriffstoken abzurufen.

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.

  2. Registrieren der App Schritte finden Sie unter Registrieren einer Anwendung beim Microsoft Identity Platform.

  3. Weisen Sie der App die Schedule.ReadWrite.All-Anwendungsberechtigungen für den Zugriff nur auf die App zu, und rufen Sie ein Zugriffstoken ab.

    Eine schritt-für-Schritt-Anleitung finden Sie unter Abrufen des Zugriffs ohne Benutzer.

    Das Zugriffstoken überprüft, ob Ihre App berechtigt ist, Microsoft Graph mithilfe ihrer eigenen Identität mithilfe der Schedule.ReadWrite.All-Berechtigung aufzurufen. Sie muss im Autorisierungsheader von Anforderungen enthalten sein.

Schritt 3: Erstellen von Teams und Zeitplänen für die Synchronisierung

Richten Sie die Teams in Teams ein, die Sie synchronisieren möchten. Sie können vorhandene Teams verwenden oder neue Teams erstellen.

  1. Richten Sie Teams in Teams so ein, dass sie den Teams und Standorten in Ihrem WFM System entsprechen. Stellen Sie sicher, dass Sie jedem Team die folgenden Personen hinzufügen:

    • Manager in Service und Produktion als Teambesitzer. Stellen Sie sicher, dass Sie den Benutzer in der MS-APP-ACTS-AS Kopfzeile als Teambesitzer jedes jeweiligen Teams hinzufügen.
    • Mitarbeiter in Service und Produktion als Teammitglieder.

  2. Erstellen Sie einen Zeitplan in Schichten für jedes Team. Weitere Informationen finden Sie unter Erstellen oder Ersetzen eines Zeitplans.

  3. Fügen Sie dem Zeitplan für jedes Team Zeitplangruppen hinzu. Zeitplangruppen werden verwendet, um Mitarbeiter basierend auf allgemeinen Merkmalen innerhalb eines Teams zu gruppieren. Bei Zeitplangruppen kann es sich z. B. um Abteilungen oder Auftragstypen handeln. Weitere Informationen finden Sie unter schedulingGroup-Ressourcentyp.

  4. Fügen Sie jeder Zeitplangruppe Mitarbeiter hinzu. Weitere Informationen finden Sie unter Ersetzen von schedulingGroup.

Hinweis

Sie können auch das Teams Admin Center verwenden, um Ihre Teams einzurichten und Schichten für die Teams bereitzustellen. Weitere Informationen finden Sie unter:

Schritt 4: Registrieren und Aktivieren der Integration von Mitarbeitern

Eine Mitarbeiterintegration definiert die Verschlüsselungseinstellungen für die Kommunikation zwischen Schichten und dem Connector, die URL für Rückrufe von Schichten und die Typen der zu synchronisierenden Entitäten.

Führen Sie die folgenden Schritte aus, um die Integration von Mitarbeitern zu registrieren und zu aktivieren:

Schritt 4a: Registrieren der Mitarbeiterintegration in Ihrem Mandanten

Sie müssen ein globaler Administrator sein, um diesen Schritt ausführen zu können.

Verwenden Sie die API zum Erstellen von workforceIntegration , um Ihre Mitarbeiterintegration in Ihrem Mandanten zu registrieren.

Hier sehen Sie ein Beispiel für eine Anforderung.

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

Weitere Informationen finden Sie in der folgenden Tabelle. Weitere Informationen finden Sie unter ressourcentyp workforceIntegration.

Eigenschaft Weitere Informationen
apiVersion API-Version für die Rückruf-URL. Ihre Basis-URL besteht aus der Url-Eigenschaft und dieser Eigenschaft.
Verschlüsselung Legen Sie das Protokoll auf fest sharedSecret. Der Geheimniswert muss genau 64 Zeichen lang sein.

Verwenden Sie das Geheimnis, um die verschlüsselten JSON-Nutzlasten zu entschlüsseln, die von Schichten an den Endpunkt Ihres Connectors gesendet werden. Die Nutzlast wird mit AES-256-CBC-HMAC-SHA256 verschlüsselt. Ihre App sollte dieses Geheimnis sicher beibehalten. Beispielsweise in einem Schlüsseltresor.
supportedEntities Geben Sie die Schichten-Entitäten an, die der Connector für die Synchronisierung unterstützen soll. Shifts ruft den /update-Endpunkt Ihres Connectors auf, wenn sich eine dieser Entitäten ändert, sodass Sie die Änderung genehmigen oder ablehnen können. Eine Liste der möglichen Werte finden Sie unter workforceIntegration-Ressourcentyp.

Anmerkung Diese Liste ist eine verteilbare Enumeration. Sie müssen den Anforderungsheader Prefer: include-unknown-enum-members verwenden, um alle Werte abzurufen.
eligibilityFilteringEnabledEntities Hinweis: Ab Oktober 2024 wird dieser Endpunkt nur in der Betaversion von Microsoft Graph-API unterstützt.

Geben Sie die Schichten-Entitäten an, die Sie für die Berechtigungsfilterung unterstützen möchten. Die folgenden Werte sind möglich:
  • none: Leere Liste
  • SwapRequests: Shifts ruft den /read-Endpunkt Ihres Connectors auf, um eine gefilterte Liste von Schichten abzurufen, aus der ein Benutzer für eine Auslagerungsanforderung auswählen kann.
  • TimeOffReasons: Shifts ruft den /read-Endpunkt Ihres Connectors auf, um eine gefilterte Liste der Gründe für die Auszeit zu erhalten, aus der ein Benutzer auswählen kann, wenn er freizeitfreie Zeit anfordert.
Anmerkung Diese Liste ist eine verteilbare Enumeration. Sie müssen den Anforderungsheader Prefer: include-unknown-enum-members verwenden, um alle Werte abzurufen.
url Die URL für die Mitarbeiterintegration für Rückrufe aus Schichten. Ihre Basis-URL besteht aus dieser Eigenschaft und der apiVerson-Eigenschaft .

Schritt 4b: Aktivieren der Mitarbeiterintegration für Ihre Teamzeitpläne

Aktivieren Sie Ihre Mitarbeiterintegration für die Zeitpläne, die Sie verwalten möchten. Verwenden Sie dazu die API Zum Erstellen oder Ersetzen von Zeitplänen , um den Zeitplan für Ihre Teams zu erstellen oder zu aktualisieren.

Hier sehen Sie ein Beispiel für eine Anforderung.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}
  • Geben Sie die workforceIntegrationId an, die beim Registrieren der Personalintegration generiert wurde.
  • Sie können maximal eine Mitarbeiterintegration nach einem Zeitplan aktivieren. Wenn Sie mehr als eine workforceIntegrationId in die Anforderung einschließen, wird die erste verwendet.

Problembehandlung

Connector

Was geschieht, wenn der Connector auf eine Anforderung von Shifts antwortet, wenn er einen anderen Antwortcode als 200 zurückgibt? Macht es einen Unterschied, ob eine andere status als 200 im Antworttext zurückgegeben wird?

Es gibt einen Unterschied zwischen diesen beiden Szenarien.

  • Wenn der Connector einen anderen Antwortcode als 200 zurückgibt, versucht Shifts, die Endpunkte /read und /update mehrmals zu wiederholen. Schließlich zeigt Shifts die Meldung "Es ist ein Fehler aufgetreten. Die Einrichtung der Mitarbeiterintegration in Ihrem Team hat mit ungültigen Daten geantwortet." Fehlermeldung.
  • Wenn der Verbinder einen anderen status als 200 im Antworttext zurückgibt, zeigt Shifts die Meldung "Es ist ein Fehler aufgetreten. Ihre Änderung konnte leider nicht abgeschlossen werden", Fehlermeldung und beendet die Wiederholung der Endpunkte.

Was geschieht, wenn der Connector ungültige Daten im Antworttext zurückgibt?

Verschiebt versuche, die Endpunkte /read und /update mehrmals zu wiederholen. Schließlich zeigt Shifts die Meldung "Es ist ein Fehler aufgetreten. Die in Ihrem Team eingerichtete Mitarbeiterintegration hat mit ungültigen Daten geantwortet." Fehlermeldung.

Gewusst wie ermitteln, ob die Anforderung ursprünglich in Schichten oder im WFM System erfolgt ist, um eine Endlosschleife zu verhindern?

Fügen Sie den X-MS-WFMPassthrough: workforceIntegratonId Header allen Schreib- und Aktualisierungsaufrufen hinzu, um die vom Connector ausgelösten Änderungen zu identifizieren bzw. zu ignorieren. Dieser Header wird verwendet, um anzugeben, dass die Anforderung aufgrund eines vorherigen Aufrufs erfolgt ist, der vom Connector an Graph-API erfolgt ist, um Daten aus Ihrem WFM System mit Schichten zu synchronisieren.

Mitarbeiterintegrationsregistrierung

Ich habe die Integration der Mitarbeiter registriert und "eligibilityFilteringEnabledEntities" angegeben, einschließlich "SwapRequest, OfferShiftRequest und TimeOffReason", aber der Antworttext zeigt nicht die Liste "eligibilityFilteringEnabledEntities" an.

Die Berechtigungsfilterung wird derzeit über den https://graph.microsoft.com/beta Endpunkt und nicht über den https://graph.microsoft.com/v1 Endpunkt unterstützt.

Ich habe die Personalintegration registriert und "supportedEntities" hinzugefügt, erhalte aber eine Antwort von 400 Ungültige Anforderung und eine "Ungültige Nutzlast: Angeforderter Wert 'shift, ....'" wurde nicht gefunden."

Stellen Sie sicher, dass jede Shifts-Entität im supportedEntities Listenanforderungstext mit einem Großbuchstaben beginnt. Beispiel: "supportedEntities":"Shift,SwapRequest,OpenShift".

Ich habe die Personalintegration registriert und die Endpunkte /connect, /update und /read implementiert, aber der Webhook funktioniert nicht.

Stellen Sie sicher, dass Ihre Mitarbeiterintegration für Ihren Teamzeitplan aktiviert ist. Überprüfen Sie außerdem, ob die Eigenschaften url und apiVersion korrekt sind.

Endpunktreferenz

Anforderung

ConnectRequest

Eigenschaft Typ Beschreibung
tenantId Zeichenfolge ID des Mandanten für die Personalintegration
userId String ID des Benutzers für die Personalintegration 
{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Eigenschaft Typ Beschreibung
Aufforderungen WfiRequest-Sammlung Liste der WfiRequests 
{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

Anzahl der Elemente in einer Anforderung:

  • In den meisten Fällen verfügt eine Anforderung über ein Element.
  • Einige Anforderungen, z. B. Genehmigungen für Wechselschichtanforderungen, haben fünf Elemente: eine PUT-Auslagerungsanforderung, zwei DELETE-Schichten (vorhandene Schichten) und zwei POST-Schichten (neue Schichten).

WfiRequest

Eigenschaft Typ Beschreibung
id String ID der Entität
Methode String Die Methode, die für das Element aufgerufen wird. Beispiel: POST, PUT, GET, , DELETE.
url Zeichenfolge Gibt den Typ der Entität und Vorgangsdetails an.
Überschriften WfiRequestHeader Header
body SchichtenEntität Der Text der Entität, die sich auf die Anforderung bezieht.
Für POST /teams/{teamId}/update
Eigenschaft Typ Beschreibung
id String ID der Entität
Methode String POST , um eine Entität zu erstellen, PUT eine Entität zu aktualisieren, DELETE um eine Entität zu löschen.
url Zeichenfolge Das Format ist /{EntityType}/{EntityId}. Mögliche Werte für {EntityType} sind shifts, swapRequests, timeoffReasons, openshifts, openshiftrequests, offershiftrequests, timesoff, . timeOffRequests Beispiel: /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
Kopfzeile WfiRequestHeader Kopfzeile
body SchichtenEntität Muss in der url-Eigenschaft übereinstimmen{EntityType}. Verwenden Sie shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Beispiel: /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
Für POST /teams/{teamsId}/read
Eigenschaft Typ Beschreibung
id String ID der Entität
Methode String Ist immer GET.
url Zeichenfolge
  • TimeOffReasons: Das Format ist /users/{userId}/timeOffReasons?requestType=TimeOffReason. Beispiel: /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason.
  • SwapRequest: Das Format ist /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Beispiel: shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
Kopfzeile WfiRequestHeader Kopfzeile
body SchichtenEntität Ist immer null.

WfiRequestHeader

Eigenschaft Typ Beschreibung
X-MS-Transaction-ID String Transaktions-ID
X-MS-Läuft ab String (DateTime) Transaktionsablauf DateTime

X-MS-WFMPassthrough: workforceIntegratonId wird nicht in WfiRequestHeader enthalten sein. Sie sollte aus der HttpRequest extrahiert werden.

Antwort

WfiResponseContainer

Eigenschaft Typ Beschreibung
Antworten WfiResponse-Auflistung Liste der WfiResponsen 
{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Eigenschaft Typ Beschreibung
id String ID der Entität
status String Ergebnis des Vorgangs
body WfiResponseBody WfiResponseBody

WfiResponseBody

Eigenschaft Typ Beschreibung
eTag String eTag
error WfiResponseError Details zum Fehler
data String Die angeforderten Daten (für Leseanforderungen)

WfiResponseError

Eigenschaft Typ Beschreibung
code String Fehlercode
message String Fehlermeldung