Delen via

Een aangepaste integratie maken om uw personeelsbeheersysteem te synchroniseren met Shifts

  • Artikel
  • Van toepassing op:
    Microsoft Teams, Microsoft 365 for frontline workers

Overzicht

Integreer Shifts, de planningsbeheer-app in Microsoft Teams, met uw systeem voor personeelsbeheer (WFM). Met deze integratie kunnen uw frontlinemedewerkers hun planningen rechtstreeks in Shifts bekijken en beheren.

In dit artikel wordt uitgelegd hoe u een connector maakt met behulp van de Microsoft Graph API om deze integratie te vergemakkelijken.

U kunt uw integratie instellen voor een gegevenssynchronisatie in één richting of een gegevenssynchronisatie in twee richtingen.

  • Eenrichtingssynchronisatie (WFM systeem naar Shifts): in deze installatie worden planningsgegevens in uw WFM-systeem gesynchroniseerd met Shifts. De connector leest de gegevens in uw WFM systeem en schrijft deze naar Shifts. Wijzigingen die door gebruikers in Shifts zijn aangebracht, worden echter niet doorgevoerd in uw WFM systeem.

  • Synchronisatie in twee richtingen (WFM systeem en Shifts): met deze instelling kunt u een synchronisatie in twee richtingen uitvoeren. Planningsgegevens in uw WFM systeem worden gesynchroniseerd met Shifts en eventuele wijzigingen die door gebruikers in Shifts zijn aangebracht, worden terug gesynchroniseerd met uw WFM systeem. De connector valideert en keurt de wijzigingen die gebruikers aanbrengen in Shifts goed volgens bedrijfsregels die worden afgedwongen door uw WFM systeem voordat de wijzigingen naar Shifts worden geschreven.

Opmerking

Als u UKG Pro WFM, Blue Yonder WFM of Reflexis WFM gebruikt, kunt u ook een beheerde connector gebruiken om Shifts te integreren met uw WFM systeem. Zie Shifts-connectors voor meer informatie.

Terminologie die in dit artikel wordt gebruikt

Term Beschrijving
connector Een app die planningsgegevens synchroniseert tussen uw WFM-systeem en Shifts.
personeelsintegratie Een entiteit die de versleutelingsmethode voor communicatie, de callback-URL voor uw connector en de Shifts-entiteiten definieert die moeten worden gesynchroniseerd.

Voordat u begint

Vereisten

  • Bepaal welke gegevens u wilt synchroniseren op basis van de behoeften van uw bedrijf.
  • Inzicht in de verificatie- en autorisatieconcepten in de Microsoft identity platform. Zie Basisbeginselen van verificatie en autorisatie.
  • Beheer rollen vereist:
    • Ten minste een cloudtoepassingsbeheerder om een app te registreren in de Microsoft Entra-beheercentrum
    • Globale beheerder om de integratie van het personeel te registreren

Raak vertrouwd met het integratieproces

Hier volgt een overzicht van de integratiestappen. Bekijk deze informatie om inzicht te krijgen in het algehele proces, inclusief wie elke stap uitvoert.

Stap Synchronisatie in één richting Synchronisatie in twee richtingen Wie voert deze stap uit
1 Uw connector maken: Uw connector maken: Developer
2 Een app registreren in de Microsoft Entra-beheercentrum Een app registreren in de Microsoft Entra-beheercentrum Een account dat ten minste een cloudtoepassingsbeheerder is
3 Teams en planningen maken voor synchronisatie Teams en planningen maken voor synchronisatie Ontwikkelaar of Teams-beheerder
4 Registreer en schakel de integratie van het personeel in: Registreer en schakel de integratie van het personeel in: Stap 4a: Globale beheerder
Stap 4b: Ontwikkelaar

Stap 1: uw connector maken

Voer de volgende stappen uit om uw connector te maken:

Stap 1a: wijzigingen in Shifts synchroniseren met uw WFM systeem

Als u uw connector wilt instellen voor het ontvangen en verwerken van aanvragen van Shifts, moet u de volgende eindpunten implementeren:

Uw basis-URL en eindpunt-URL's bepalen

De basis-URL (webhook) is {url}/v{apiVersion}, waarbij URL en apiVersion de eigenschappen zijn die u instelt in het workforceIntegration-object wanneer u de personeelsintegratie registreert.

De relatieve paden van de eindpunt-URL's zijn als volgt:

  • /verbinden: /connect
  • /update: /teams/{teamid}/update
  • /lezen: /teams/{teamid}/read

Als url bijvoorbeeld is https://contosoconnector.com/wfi en apiVersion is 1:

  • De basis-URL is https://contosoconnector/com/wfi/v1.
  • Het eindpunt /connect is https://contosoconnector/wfi/v1/connect.
  • Het /update-eindpunt is https://contosoconnector/wfi/v1/teams/{teamid}/update.
  • Het /read-eindpunt is https://contosoconnector/wfi/v1/teams/{teamid}/read.

Versleuteling

Alle aanvragen worden versleuteld met AES-256-CBC-HMAC-SHA256. U geeft de gedeelde geheime sleutel op wanneer u de integratie van het personeel registreert. Antwoorden die naar Shifts worden teruggestuurd, mogen niet worden versleuteld.

Eindpunten

POST /connect

Shifts roept dit eindpunt aan om de verbinding te testen wanneer u de integratie van het personeel registreert. Een geslaagd antwoord wordt alleen geretourneerd als dit eindpunt een HTTP-antwoord 200 OK retourneert.

Voorbeeld

Verzoek
ConnectRequest

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

Antwoord
HTTP retourneren 200 OK

POST /teams/{teamid}/update

Shifts roept dit eindpunt aan om goedkeuring te krijgen wanneer een wijziging wordt aangebracht in een Shifts-entiteit in een planning die is ingeschakeld voor de integratie van het personeel. Als dit eindpunt de aanvraag goedkeurt, wordt de wijziging opgeslagen in Shifts.

Aangezien uw WFM systeem het systeem van record is, moet de connector eerst proberen de wijziging aan te brengen in het WFM systeem wanneer de connector een aanvraag voor dit eindpunt ontvangt. Als de wijziging is geslaagd, retourneert u geslaagd. Anders retourneert u een fout.

Shifts roept dit eindpunt aan voor elke wijziging (inclusief wijzigingen die zijn geïnitieerd vanuit het connector-/WFM-systeem). Als de connector een update naar Shifts heeft verzonden met behulp van Graph API en de X-MS-WFMPassthrough: workforceIntegratonId header heeft toegevoegd, heeft de aanvraag die naar dit eindpunt komt dezelfde header, zodat u deze aanvragen op de juiste manier kunt identificeren en afhandelen. Retourneer bijvoorbeeld succes zonder dezelfde wijziging aan te brengen in het WFM-systeem als deze redundant zou zijn en ertoe kan leiden dat de connector vastloopt in een oneindige lus.

In het volgende diagram ziet u de gegevensstroom.

Diagram met de stroom voor updates van Shifts naar uw WFM systeem.

Opmerking

Zie WfiRequest in de sectie Eindpuntverwijzing van dit artikel voor meer informatie over aanvraag- en antwoordmodellen.

Antwoordcode retourneren
Elk antwoord van de integratie, inclusief een fout, moet een HTTP-antwoordcode 200 OKhebben. De hoofdtekst van het antwoord moet de status en het foutbericht hebben die de juiste foutstatus van de sub-aanroep aangeven. Elk antwoord van de integratie anders dan 200 OK wordt behandeld als een fout en geretourneerd naar de aanroeper (client of Microsoft Graph).

Als u een synchronisatie in één richting wilt instellen, maakt u Shifts alleen-lezen

Voor een synchronisatie in één richting moet u Shifts alleen-lezen maken, zodat gebruikers geen wijzigingen kunnen aanbrengen in Shifts. Als u Shifts alleen-lezen wilt maken, retourneert u een foutreactie voor alle aanvragen van Shifts.

Als u bijvoorbeeld wilt voorkomen dat gebruikers wijzigingen aanbrengen in shifts in de planning, moet dit eindpunt een foutreactie retourneren wanneer het een aanvraag met betrekking tot een shift entiteit ontvangt.

Voorbeeld

Verzoek
WfiRequestContainer

In het volgende voorbeeld ziet u een aanvraag van Shifts waarin wordt gevraagd of een dienst, waarvan de id SHFT_12345678-1234-1234-1234-123467890ab en de eigenschappen heeft die in hoofdtekst worden vermeld, kan worden opgeslagen in Shifts. Deze aanvraag is geactiveerd wanneer een gebruiker een shift maakt in 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"
      }
    }
  ]
}

Antwoord
WfiResponse

Geslaagd: HTTP retourneren 200 OK

In dit voorbeeld ziet u het antwoord dat wordt geretourneerd als het eindpunt de aanvraag heeft goedgekeurd. In dit scenario wordt de dienst opgeslagen in Shifts en kan de gebruiker de dienst in de planning zien.

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

Fout: HTTP retourneren 200 OK

In dit voorbeeld ziet u het antwoord dat is geretourneerd als het eindpunt de aanvraag heeft geweigerd. In dit scenario ontvangt de gebruiker het foutbericht 'Kan de dienst niet toevoegen' in 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

Dit eindpunt verwerkt aanvragen van Shifts om in aanmerking komende verlofredenen of in aanmerking komende diensten voor wisselaanvragen voor een gebruiker op te halen.

Opmerking

Vanaf oktober 2024 wordt dit eindpunt alleen ondersteund in de bètaversie van de Microsoft Graph API. U moet ook waarden opgeven voor de eigenschap eligibilityFilteringEnabledEntities wanneer u de personeelsintegratie registreert.

In het volgende diagram ziet u de gegevensstroom.

Diagram met de stroom voor aanvragen voor geschiktheidsfilters.

Antwoordcode retourneren
Elk antwoord van de integratie, inclusief een fout, moet een HTTP-antwoordcode 200 OKhebben. De hoofdtekst van het antwoord moet de status en het foutbericht bevatten die de juiste foutstatus van de sub-aanroep aangeven. Elk antwoord van de integratie anders dan 200 OK wordt behandeld als een fout en geretourneerd naar de aanroeper (client of Microsoft Graph).

Voorbeeld: TimeOffReason

Verzoek

In het volgende voorbeeld ziet u een aanvraag van Shifts waarin wordt gevraagd voor welke verlofredenen een gebruiker (gebruikers-id aa162a04-bec6-4b81-ba99-96caa7b2b24d) in aanmerking komt. Deze aanvraag is geactiveerd wanneer de gebruiker verlof aanvraagt in Shifts.

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

Antwoord
Geslaagd: HTTP retourneren 200 OK

In het volgende antwoord ziet u dat de in aanmerking komende reden-id's voor verlof voor de gebruiker 'TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc' en 'TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d' zijn. In dit scenario ziet de gebruiker de bijbehorende verlofredenen om uit te kiezen in 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 
          } 
        }
    ]
}

Fout: HTTP retourneren 200 OK

In dit voorbeeld wordt een foutbericht geretourneerd omdat de connector het WFM-systeem niet kan bereiken om verlofredenen voor de gebruiker op te halen.

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

Verzoek

In het volgende voorbeeld ziet u een aanvraag van Shifts waarin wordt gevraagd welke diensten in aanmerking komen voor een wissel met de dienst met de id SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 tussen 2024-1 01T04:00:00.0000000Z en 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"
    }
  ]
}

Antwoord
Geslaagd: HTTP retourneren 200 OK

Het volgende antwoord laat zien dat de dienst kan worden verwisseld met de dienst waarvan de id SHFT_98e96e23-966b-43be-b90d-4697037b67af is.

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

Fout: HTTP retourneren 200 OK

In dit voorbeeld wordt een foutbericht geretourneerd omdat de connector het WFM-systeem niet kan bereiken om in aanmerking komende diensten op te halen voor een wisselaanvraag voor de gebruiker.

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

Stap 1b: gegevens van uw WFM-systeem synchroniseren met Shifts

Gebruik Shifts-API's in Microsoft Graph om planningsgegevens uit uw WFM systeem te lezen en de gegevens naar Shifts te schrijven.

Als u bijvoorbeeld een dienst wilt toevoegen aan Shifts, gebruikt u de DIENST-API maken .

Zie de Microsoft Graph API v1.0-verwijzing voor Shifts-API's, die worden vermeld onder Shift-beheer.

Opmerking

De MS-APP-ACTS-AS header is vereist voor aanvragen en moet de id (GUID) bevatten van de gebruiker waarvoor uw app handelt. U wordt aangeraden de gebruikers-id van een teameigenaar te gebruiken bij het bijwerken van de planning.

In het volgende diagram ziet u de gegevensstroom.

Diagram met de stroom voor het synchroniseren van gegevens van uw WFM systeem naar Shifts.

Eerste synchronisatie

Voor de eerste synchronisatie moet de connector gegevens in uw WFM-systeem lezen en de gegevens naar Shifts schrijven. We raden u aan om twee weken aan toekomstige gegevens te synchroniseren.

Na de eerste synchronisatie

Na de eerste synchronisatie kunt u het volgende doen:

  • Shifts synchroon bijwerken met wijzigingen in uw WFM systeem: verzend een update naar Shifts voor elke wijziging die in uw WFM systeem is aangebracht.

  • Asynchroon shifts bijwerken met wijzigingen in uw WFM systeem: voer een periodieke synchronisatie uit door alle wijzigingen die in uw WFM systeem zijn opgetreden binnen een bepaald tijdsbestek (bijvoorbeeld 10 minuten) naar Shifts te schrijven.

    Alle schrijfbewerkingen naar Shifts, inclusief schrijfbewerkingen die door de connector zijn gestart, activeren een aanroep naar het /update-eindpunt van de connector. U wordt aangeraden de X-MS-WFMPassthrough: workforceIntegratonId header op te nemen voor alle schrijfoproepen, zodat de connector deze op de juiste manier kan identificeren en afhandelen. Als uw WFM systeem bijvoorbeeld de wijziging heeft geïnitieerd, keurt u deze goed zonder een update toe te passen op uw WFM systeem.

    Opmerking

    Als u uw connector instelt voor een tweerichtingssynchronisatie van gegevens tussen uw WFM-systeem en Shifts, sluit u wijzigingen uit die zijn geïnitieerd vanuit Shifts in de periodieke synchronisatie. Deze wijzigingen zijn al geschreven in Shifts.

Stap 2: een app registreren in de Microsoft Entra-beheercentrum

Volg deze stappen om een app voor uw connector te registreren in de Microsoft identity platform, machtigingen voor de app te configureren voor toegang tot Microsoft Graph en een toegangstoken op te halen.

  1. Meld u aan bij de Microsoft Entra-beheercentrum als ten minste een cloudtoepassingsbeheerder.

  2. Registreer uw app. Zie Een toepassing registreren bij de Microsoft identity platform voor stappen.

  3. Wijs de toepassingsmachtigingenSchedule.ReadWrite.All toe aan de app voor alleen-app-toegang en haal een toegangstoken op.

    Zie Toegang krijgen zonder gebruiker voor stapsgewijze instructies.

    Het toegangstoken controleert of uw app is gemachtigd om Microsoft Graph aan te roepen met behulp van een eigen identiteit met behulp van de machtiging Schedule.ReadWrite.All . Deze moet worden opgenomen in de autorisatieheader van aanvragen.

Stap 3: teams en planningen voor synchronisatie maken

Stel de teams in Teams in die u wilt synchroniseren. U kunt bestaande teams gebruiken of nieuwe teams maken.

  1. Stel teams in Teams in om te corresponderen met de teams en locaties in uw WFM systeem. Zorg ervoor dat u de volgende personen aan elk team toevoegt:

    • Frontlinemanagers als teameigenaren. Zorg ervoor dat u de gebruiker in de MS-APP-ACTS-AS header toevoegt als teameigenaar van elk team.
    • Frontlijnmedewerkers als teamleden.

  2. Maak een planning in Shifts voor elk team. Zie Planning maken of vervangen voor meer informatie.

  3. Voeg planningsgroepen toe aan de planning van elk team. Planningsgroepen worden gebruikt om werknemers te groepeert op basis van gemeenschappelijke kenmerken binnen een team. Planningsgroepen kunnen bijvoorbeeld afdelingen of taaktypen zijn. Zie schedulingGroup-resourcetype voor meer informatie.

  4. Werknemers toevoegen aan elke planningsgroep. Zie SchedulingGroup vervangen voor meer informatie.

Opmerking

U kunt ook het Teams-beheercentrum gebruiken om uw teams in te stellen en Shifts in de teams te implementeren. Hier vindt u meer informatie:

Stap 4: De integratie van het personeel registreren en inschakelen

Een personeelsintegratie definieert de versleutelingsinstellingen voor communicatie tussen Shifts en de connector, de URL voor callbacks van Shifts en de typen entiteiten die moeten worden gesynchroniseerd.

Voer de volgende stappen uit om de integratie van het personeel te registreren en in te schakelen:

Stap 4a: De integratie van het personeelsbestand in uw tenant registreren

U moet een globale beheerder zijn om deze stap uit te voeren.

Gebruik de Create workforceIntegration-API om uw personeelsintegratie in uw tenant te registreren.

Hier volgt een voorbeeld van een aanvraag.

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

Zie de volgende tabel voor meer informatie. Zie workforceIntegration-resourcetype voor meer informatie.

Eigenschap Meer informatie
apiVersion API-versie voor de callback-URL. Uw basis-URL bestaat uit de eigenschap URL en deze eigenschap.
versleuteling Stel protocol in op sharedSecret. De geheime waarde moet precies 64 tekens bevatten.

Gebruik het geheim om de versleutelde JSON-nettoladingen te ontsleutelen die vanuit Shifts naar het eindpunt van uw connector worden verzonden. De nettolading wordt versleuteld met AES-256-CBC-HMAC-SHA256. Uw app moet dit geheim veilig behouden. Bijvoorbeeld in een sleutelkluis.
ondersteunde entiteiten Geef de Shifts-entiteiten op die de connector moet ondersteunen voor synchronisatie. Shifts roept het /update-eindpunt van uw connector aan wanneer een van deze entiteiten wordt gewijzigd, zodat u de wijziging kunt goedkeuren of weigeren. Zie workforceIntegration-resourcetype voor de lijst met mogelijke waarden

Notitie Deze lijst is een suggestiebare opsomming. U moet de Prefer: include-unknown-enum-members aanvraagheader gebruiken om alle waarden op te halen.
eligibilityFilteringEnabled Entiteiten Opmerking: vanaf oktober 2024 wordt dit eindpunt alleen ondersteund in de bètaversie van de Microsoft Graph API.

Geef de Shifts-entiteiten op die u wilt verbinden voor het filteren van geschiktheid. Mogelijke waarden zijn:
  • none: Lege lijst
  • SwapRequests: Shifts roept het /read-eindpunt van uw connector aan om een gefilterde lijst met diensten op te halen waaruit een gebruiker kan kiezen voor een wisselaanvraag.
  • TimeOffReasons: Shifts roept het /read-eindpunt van uw connector aan om een gefilterde lijst met verlofredenen op te halen waaruit een gebruiker kan kiezen wanneer ze verlof aanvragen.
Notitie Deze lijst is een suggestiebare opsomming. U moet de Prefer: include-unknown-enum-members aanvraagheader gebruiken om alle waarden op te halen.
url De URL voor personeelsintegratie voor callbacks vanuit Shifts. Uw basis-URL bestaat uit deze eigenschap en de eigenschap apiVerson .

Stap 4b: De integratie van het personeel voor uw teamplanningen inschakelen

Schakel de integratie van uw personeel in volgens de planningen die u wilt beheren. Gebruik hiervoor de PLANNING-API maken of vervangen om de planning voor uw teams te maken of bij te werken.

Hier volgt een voorbeeld van een aanvraag.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}
  • Geef de workforceIntegrationId op die is gegenereerd toen u de personeelsintegratie registreerde.
  • U kunt maximaal één personeelsintegratie volgens een schema inschakelen. Als u meer dan één workforceIntegrationId in de aanvraag opneemt, wordt de eerste gebruikt.

Problemen oplossen

Connector

Wanneer de connector reageert op een aanvraag van Shifts, wat gebeurt er dan als deze een andere antwoordcode dan 200 retourneert? Maakt het verschil als er een andere status dan 200 wordt geretourneerd in de hoofdtekst van het antwoord?

Er is een verschil tussen deze twee scenario's.

  • Als de connector een andere antwoordcode dan 200 retourneert, probeert Shifts de eindpunten /read en /update meerdere keren opnieuw te proberen. Uiteindelijk geeft Shifts de tekst 'Er is iets misgegaan. Het instellen van de integratie van het personeel in uw team heeft gereageerd met ongeldige gegevens.' foutbericht.
  • Als de connector een andere status dan 200 retourneert in de antwoordtekst, geeft Shifts de tekst 'Er is iets misgegaan. De wijziging kan niet worden voltooid, wordt het foutbericht weergegeven en het opnieuw proberen van de eindpunten wordt gestopt.

Wat gebeurt er als de connector ongeldige gegevens retourneert in de hoofdtekst van het antwoord?

Shifts probeert de eindpunten /read en /update meerdere keren opnieuw uit te voeren. Uiteindelijk geeft Shifts de tekst 'Er is iets misgegaan. De werknemersintegratie die is ingesteld voor uw team, heeft gereageerd met ongeldige gegevens.' foutbericht.

Hoe kan ik bepalen of de aanvraag oorspronkelijk is gedaan in Shifts of in het WFM-systeem om een oneindige lus te voorkomen?

Voeg de X-MS-WFMPassthrough: workforceIntegratonId header toe aan alle schrijf- en update-aanroepen om de wijzigingen te identificeren/negeren die door de connector worden geactiveerd. Deze header wordt gebruikt om aan te geven dat de aanvraag wordt gedaan vanwege een voorgaande aanroep die is gedaan door de connector om te Graph API gegevens van uw WFM systeem te synchroniseren met Shifts.

Registratie van personeelsintegratie

Ik heb de integratie van het personeel geregistreerd en 'eligibilityFilteringEnabledEntities' opgegeven, waaronder 'SwapRequest, OfferShiftRequest en TimeOffReason', maar in de antwoordtekst wordt de lijst 'eligibilityFilteringEnabledEntities' niet weergegeven.

Geschiktheidsfiltering wordt momenteel ondersteund via het https://graph.microsoft.com/beta eindpunt, niet via het https://graph.microsoft.com/v1 eindpunt.

Ik heb de integratie van het personeel geregistreerd en 'ondersteunde entiteiten' toegevoegd, maar ik ontvang een 400 ongeldige aanvraag en een 'Ongeldige nettolading: aangevraagde waarde 'shift, ....' is niet gevonden.

Zorg ervoor dat elke Shifts-entiteit in de hoofdtekst van de supportedEntities lijstaanvraag begint met een hoofdletter. Bijvoorbeeld "supportedEntities":"Shift,SwapRequest,OpenShift".

Ik heb de integratie van het personeel geregistreerd en de eindpunten /connect, /update en /read geïmplementeerd, maar de webhook werkt niet.

Zorg ervoor dat uw personeelsintegratie is ingeschakeld voor uw teamplanning. Controleer ook of de eigenschappen url en apiVersion juist zijn.

Eindpuntreferentie

Verzoek

ConnectRequest

Eigenschap Type Beschrijving
tenantId Tekenreeks Id van de tenant voor de integratie van het personeel
userId Tekenreeks Id van de gebruiker voor de integratie van het personeel 
{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Eigenschap Type Beschrijving
Verzoeken WfiRequest-verzameling Lijst met WfiRequests 
{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

Aantal elementen in een aanvraag:

  • In de meeste gevallen heeft een aanvraag één element.
  • Sommige aanvragen, zoals goedkeuringen voor wisseldienstaanvragen, hebben vijf elementen: één PUT-wisselaanvraag, twee DELETE-diensten (bestaande diensten) en twee POST-diensten (nieuwe diensten).

WfiRequest

Eigenschap Type Beschrijving
in Tekenreeks Id van de entiteit
methode Tekenreeks De methode die is aangeroepen voor het item. Bijvoorbeeld POST, PUT, GET, DELETE.
url Tekenreeks Geeft het type entiteit en bewerkingsdetails aan.
Headers WfiRequestHeader Headers
lichaam ShiftsEntity Hoofdtekst van de entiteit met betrekking tot de aanvraag.
Voor POST /teams/{teamId}/update
Eigenschap Type Beschrijving
in Tekenreeks Id van de entiteit
methode Tekenreeks POST om een entiteit te maken, PUT om een entiteit bij te werken, DELETE om een entiteit te verwijderen.
url Tekenreeks De indeling is /{EntityType}/{EntityId}. Mogelijke waarden voor {EntityType} zijn shifts, swapRequests, timeoffReasons, openshifts, openshiftrequests, offershiftrequeststimesoff, , . timeOffRequests Bijvoorbeeld /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
rubriek WfiRequestHeader Header
lichaam ShiftsEntity Moet overeenkomen {EntityType} in de eigenschap URL . Gebruik een van shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Bijvoorbeeld /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
Voor POST /teams/{teamsId}/read
Eigenschap Type Beschrijving
in Tekenreeks Id van de entiteit
methode Tekenreeks Is altijd GET.
url Tekenreeks
  • TimeOffReasons: de indeling is /users/{userId}/timeOffReasons?requestType=TimeOffReason. Bijvoorbeeld /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason.
  • SwapRequest: De indeling is /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Bijvoorbeeld shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
rubriek WfiRequestHeader Header
lichaam ShiftsEntity Is altijd null.

WfiRequestHeader

Eigenschap Type Beschrijving
X-MS-Transaction-ID Tekenreeks Transactie-id
X-MS-verloopt Tekenreeks (Datum/tijd) Vervaldatum van transactie datum/tijd

X-MS-WFMPassthrough: workforceIntegratonId wordt niet opgenomen in WfiRequestHeader. Deze moet worden geëxtraheerd uit de HttpRequest.

Antwoord

WfiResponseContainer

Eigenschap Type Beschrijving
Reacties WfiResponse-verzameling Lijst met WfiResponses 
{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Eigenschap Type Beschrijving
in Tekenreeks Id van de entiteit
status Tekenreeks Resultaat van de bewerking
lichaam WfiResponseBody WfiResponseBody

WfiResponseBody

Eigenschap Type Beschrijving
eTag Tekenreeks eTag
fout WfiResponseError Details over de fout
gegevens Tekenreeks De aangevraagde gegevens (voor leesaanvragen)

WfiResponseError

Eigenschap Type Beschrijving
code Tekenreeks Foutcode
bericht Tekenreeks Foutbericht