Del via

Opret en brugerdefineret integration for at synkronisere dit system til styring af arbejdsstyrken med Skift

  • Artikel
  • Gælder for:
    Microsoft Teams, Microsoft 365 for frontline workers

Oversigt

Integrer Shifts, appen til styring af tidsplaner i Microsoft Teams, med dit system til administration af arbejdsstyrken (WFM). Denne integration gør det muligt for din frontlinearbejdsstyrke at få vist og administrere deres tidsplaner direkte i skift.

I denne artikel kan du se, hvordan du opretter en connector ved hjælp af Microsoft Graph API for at lette denne integration.

Du kan konfigurere din integration til enten en envejsdatasynkronisering eller en tovejsdatasynkronisering.

  • Envejssynkronisering (WFM system til skift): I denne konfiguration synkroniseres planlægningsdata i dit WFM system til Skift. Connectoren læser dataene i dit WFM system og skriver dem til Skift. Ændringer foretaget i skift foretaget af brugere afspejles dog ikke tilbage i dit WFM system.

  • Tovejssynkronisering (WFM system og skift): Denne konfiguration muliggør en tovejssynkronisering. Planlæg data i dit WFM system synkroniseres til Skift, og alle ændringer, som brugerne foretager i Skift, synkroniseres tilbage til dit WFM system. Connectoren validerer og godkender de ændringer, brugerne foretager i Skift i henhold til de forretningsregler, der gennemtvinges af dit WFM system, før ændringerne skrives til Skift.

Bemærk!

Hvis du bruger UKG Pro-WFM, Blue Yonder WFM eller Reflexis WFM, kan du også bruge en administreret connector til at integrere Shifts med dit WFM system. Du kan få mere at vide under Skift-connectors.

Terminologi, der bruges i denne artikel

Vilkår Beskrivelse
Stik En app, der synkroniserer tidsplandata mellem dit WFM system og Skift.
integration af arbejdsstyrke Et objekt, der definerer krypteringsmetoden for kommunikation, URL-adressen til tilbagekald for din connector og de Shifts-enheder, der skal synkroniseres.

Før du begynder

Forudsætninger

  • Find ud af, hvilke data du vil synkronisere i henhold til din virksomheds behov.
  • Forstå begreberne godkendelse og godkendelse i Microsoft-identitetsplatform. Se Grundlæggende oplysninger om godkendelse og godkendelse.
  • Administration roller er påkrævet:
    • Mindst en cloudprogramadministrator for at registrere en app i Microsoft Entra-administrationscenter
    • Global administrator til registrering af integration af arbejdsstyrken

Bliv fortrolig med integrationsprocessen

Her er en oversigt over integrationstrinnene. Gennemse disse oplysninger for at få en forståelse af den overordnede proces, herunder hvem der udfører hvert trin.

Skridt Envejssynkronisering Tovejssynkronisering Hvem udfører dette trin?
1 Opret din connector: Opret din connector: Developer
2 Registrer en app i Microsoft Entra-administrationscenter Registrer en app i Microsoft Entra-administrationscenter En konto, der som minimum er cloudprogramadministrator
3 Opret teams og tidsplaner til synkronisering Opret teams og tidsplaner til synkronisering Udvikler eller Teams-administrator
4 Registrer og aktivér integration af arbejdsstyrken: Registrer og aktivér integration af arbejdsstyrken: Trin 4a: Global administrator
Trin 4b: Udvikler

Trin 1: Opret din connector

Hvis du vil oprette din connector, skal du udføre følgende trin:

Trin 1a: Synkroniser ændringer, der er foretaget i Skift til dit WFM system

Hvis du vil konfigurere din connector til at modtage og behandle anmodninger fra Skifts, skal du implementere følgende slutpunkter:

Bestem URL-adresserne for basis-URL-adressen og slutpunktet

Den grundlæggende URL-adresse (webhook) er {url}/v{apiVersion}, hvor URL-adresse og apiVersion er de egenskaber, du angiver i objektet workforceIntegration , når du registrerer integration af arbejdsstyrken.

De relative stier for URL-adresserne for slutpunktet er som følger:

  • /forbinde: /connect
  • /opdatering: /teams/{teamid}/update
  • /læse: /teams/{teamid}/read

Hvis URL-adressen f.eks. er https://contosoconnector.com/wfi , og apiVersion er 1:

  • Basis-URL-adressen er https://contosoconnector/com/wfi/v1.
  • Slutpunktet /connect er https://contosoconnector/wfi/v1/connect.
  • Slutpunktet /update er https://contosoconnector/wfi/v1/teams/{teamid}/update.
  • Slutpunktet /read er https://contosoconnector/wfi/v1/teams/{teamid}/read.

Kryptering

Alle anmodninger krypteres ved hjælp af AES-256-CBC-HMAC-SHA256. Du angiver den delte hemmelige nøgle, når du registrerer integrationen af arbejdsstyrken. Svar, der sendes tilbage til Skift, bør ikke krypteres.

Slutpunkter

POST /connect

Skift kalder dette slutpunkt for at teste forbindelsen, når du registrerer integrationen af arbejdsstyrken. Et vellykket svar returneres kun, hvis dette slutpunkt returnerer et HTTP-svar 200 OK .

Eksempel

Bøn
ConnectRequest

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

Svar
Returner HTTP 200 OK

POST /teams/{teamid}/update

Shifts kalder dette slutpunkt for at få godkendelse, når der foretages en ændring af en Shifts-enhed i en tidsplan , der er aktiveret til integration af arbejdsstyrken. Hvis dette slutpunkt godkender anmodningen, gemmes ændringen i Skift.

Da dit WFM system er postsystemet, skal det første forsøg på at foretage ændringen i det WFM system, når connectoren modtager en anmodning til dette slutpunkt. Hvis ændringen lykkes, skal du returnere succes. Ellers returneres fejl.

Skift kalder dette slutpunkt for hver ændring (herunder ændringer, der er startet fra connectoren/WFM systemet). Hvis connectoren har sendt en opdatering til Skifts ved hjælp af Graph API og tilføjet headeren X-MS-WFMPassthrough: workforceIntegratonId , har den anmodning, der kommer til dette slutpunkt, den samme header, hvilket giver dig mulighed for at identificere og håndtere disse anmodninger korrekt. Hvis du f.eks. returnerer succes uden at foretage den samme ændring i WFM systemet, som det ville være overflødigt, kan det medføre, at connectoren sidder fast i en uendelig løkke.

I følgende diagram vises dataflowet.

Diagram, der viser flowet for opdateringer fra Skift til dit WFM system.

Bemærk!

Du kan finde flere oplysninger om anmodnings- og svarmodeller under WfiRequest i afsnittet Slutpunktreference i denne artikel.

Returner svarkode
Alle svar fra integrationen, herunder en fejl, skal have en HTTP-svarkode 200 OK. Svarteksten skal have den status og fejlmeddelelse, der afspejler den relevante fejltilstand for underopkaldet. Ethvert svar fra integrationen, bortset 200 OK fra , behandles som en fejl og returneres til kalderen (klient eller Microsoft Graph).

Hvis du vil konfigurere en envejssynkronisering, skal du gøre Skift skrivebeskyttet

I forbindelse med en envejssynkronisering skal du skrivebeskytte Skift, så brugerne ikke kan foretage ændringer i Skift. Hvis du vil gøre Shifts skrivebeskyttet, skal du returnere et fejlsvar for alle anmodninger fra Skift.

Hvis du f.eks. vil forhindre brugere i at foretage ændringer af ændringer i tidsplanen, skal dette slutpunkt returnere et fejlsvar, når det modtager en anmodning vedrørende en shift enhed.

Eksempel

Bøn
WfiRequestContainer

I følgende eksempel vises en anmodning fra Skifts, hvor du bliver spurgt, om et skift, hvis id er SHFT_12345678-1234-1234-1234-1234567890ab og har de egenskaber, der er angivet i brødteksten, kan gemmes i Skift. Denne anmodning blev udløst, da en bruger opretter et skift i skiftehold.

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

Svar
WfiResponse

Udført: Returner HTTP 200 OK

I dette eksempel vises det svar, der returneres, hvis slutpunktet godkendte anmodningen. I dette scenarie gemmes skiftet i Skift, og brugeren kan se skiftet i tidsplanen.

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

Fejl: Returner HTTP 200 OK

I dette eksempel vises det svar, der returneres, hvis slutpunktet afviste anmodningen. I dette scenarie får brugeren vist fejlmeddelelsen "Skift kunne ikke tilføjes" i Skiftehold.

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

Dette slutpunkt håndterer anmodninger fra Skift for at hente berettigede fridagsårsager eller berettigede skift for swapanmodninger for en bruger.

Bemærk!

Fra og med oktober 2024 understøttes dette slutpunkt kun i betaversionen af Microsoft Graph API. Du skal også angive værdier for egenskaben eligibilityFilteringEnabledEntities , når du registrerer medarbejderintegrationen.

I følgende diagram vises dataflowet.

Diagram, der viser flowet for anmodninger om filtrering af berettigelse.

Returner svarkode
Alle svar fra integrationen, herunder en fejl, skal have en HTTP-svarkode 200 OK. Svarteksten skal indeholde den status og fejlmeddelelse, der afspejler den relevante fejltilstand for underopkaldet. Ethvert svar fra integrationen, bortset 200 OK fra , behandles som en fejl og returneres til kalderen (klient eller Microsoft Graph).

Eksempel: TimeOffReason

Bøn

I følgende eksempel vises en anmodning fra Skifts, der spørger, hvilke fridag årsager en bruger (bruger-id aa162a04-bec6-4b81-ba99-96caa7b2b24d) er berettiget til. Denne anmodning blev udløst, da brugeren anmoder om fridag i Skiftehold.

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

Svar
Udført: Returner HTTP 200 OK

Følgende svar viser, at de berettigede id'er for årsag til fridag for brugeren er "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" og "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". I dette scenarie får brugeren vist de tilsvarende fridagsårsager at vælge imellem i Skift.

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

Fejl: Returner HTTP 200 OK

I dette eksempel returneres der et fejlsvar, fordi connectoren ikke kunne få forbindelse til det WFM system for at hente årsager til fridag for brugeren.

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

Bøn

I følgende eksempel vises en anmodning fra Skift, der spørger, hvilke skift der er berettiget til en swap med det skift, hvis id er SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 mellem 2024-2024-2024 10-01T04:00:00.0000000Z og 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"
    }
  ]
}

Svar
Udført: Returner HTTP 200 OK

Følgende svar viser, at skiftet kan byttes med skiftet, hvis id er 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, 
      } 
    }
  ]
}

Fejl: Returner HTTP 200 OK

I dette eksempel returneres der et fejlsvar, fordi connectoren ikke kunne få forbindelse til det WFM system for at hente kvalificerede skift til en swapanmodning for brugeren.

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

Trin 1b: Synkroniser data fra dit WFM system til skift

Brug Skift-API'er i Microsoft Graph til at læse planlægningsdata fra dit WFM system og skrive dataene til Skift.

Hvis du f.eks. vil føje et skift til Skift, skal du bruge API'en Opret skift .

Se Referencen til Microsoft Graph API v1.0 for Skift-API'er, der er angivet under Skift-administration.

Bemærk!

Headeren MS-APP-ACTS-AS er påkrævet i anmodninger og skal indeholde id'et (GUID) for den bruger, din app handler på vegne af. Vi anbefaler, at du bruger bruger-id'et for en teamejer, når du opdaterer tidsplanen.

I følgende diagram vises dataflowet.

Diagram, der viser flowet til synkronisering af data fra dit WFM system til Skift.

Indledende synkronisering

Ved den første synkronisering skal connectoren læse data i dit WFM system og skrive dataene til Skift. Vi anbefaler, at du synkroniserer to ugers fremtidige data.

Efter den indledende synkronisering

Efter den første synkronisering kan du vælge at:

  • Synkront opdatere Skift med ændringer i dit WFM system: Send en opdatering til Skift for hver ændring, der foretages i dit WFM system.

  • Asynkront opdatere Skift med ændringer i dit WFM system: Udfør en periodisk synkronisering ved at skrive alle de ændringer, der opstod i dit WFM system inden for en bestemt tidsramme (f.eks. 10 minutter) til Skift.

    Alle skrivehandlinger til Skift, herunder skrivehandlinger, der er initieret af connectoren, udløser et kald til connectorens /update-slutpunkt. Vi anbefaler, at du inkluderer headeren X-MS-WFMPassthrough: workforceIntegratonId til alle skrivekald, så connectoren kan identificere og håndtere dem korrekt. Hvis dit WFM system f.eks. startede ændringen, skal du godkende den uden at anvende en opdatering på dit WFM system.

    Bemærk!

    Hvis du konfigurerer din connector til en tovejssynkronisering af data mellem dit WFM system og Skift, skal du udelade ændringer, der er startet fra Skift, i den periodiske synkronisering. Disse ændringer er allerede skrevet i skiftehold.

Trin 2: Registrer en app i Microsoft Entra-administrationscenter

Følg disse trin for at registrere en app til din connector i Microsoft-identitetsplatform, konfigurere tilladelser for appen for at få adgang til Microsoft Graph og få et adgangstoken.

  1. Log på Microsoft Entra-administrationscenter som mindst en cloudprogramadministrator.

  2. Registrer din app. Du kan finde trin under Registrer et program med Microsoft-identitetsplatform.

  3. Tildel Schedule.ReadWrite.Alleprogramtilladelser til appen for kun at få adgang til appen, og hent et adgangstoken.

    Du kan finde en trinvis vejledning under Få adgang uden en bruger.

    Adgangstokenet kontrollerer, at din app er godkendt til at kalde Microsoft Graph ved hjælp af sin egen identitet ved hjælp af tilladelsen Schedule.ReadWrite.All . Den skal inkluderes i godkendelsesheaderen for anmodninger.

Trin 3: Opret teams og tidsplaner for synkronisering

Konfigurer de teams i Teams, du vil synkronisere. Du kan bruge eksisterende teams eller oprette nye teams.

  1. Konfigurer teams i Teams, så de svarer til teams og placeringer i dit WFM system. Sørg for, at du føjer følgende personer til hvert team:

    • Frontlineledere som teamejere. Sørg for at tilføje brugeren i overskriften MS-APP-ACTS-AS som teamejer af hvert enkelt team.
    • Frontlinjearbejdere som teammedlemmer.

  2. Opret en tidsplan i Skift for hvert team. Du kan få mere at vide under Opret eller erstat tidsplan.

  3. Føj tidsplangrupper til tidsplanen for hvert team. Planlægningsgrupper bruges til at gruppere medarbejdere baseret på fælles egenskaber i et team. Planlægningsgrupper kan f.eks. være afdelinger eller jobtyper. Du kan få mere at vide under planlægningGrupperessourcetype.

  4. Føj medarbejdere til hver planlægningsgruppe. Du kan få mere at vide under Erstat planlægningsgruppe.

Bemærk!

Du kan også bruge Teams Administration til at konfigurere dine teams og udrulle skift til teams. Du kan få mere at vide under:

Trin 4: Registrer og aktivér integration af arbejdsstyrken

En integration af en arbejdsstyrke definerer krypteringsindstillingerne for kommunikation mellem Skift og connectoren, URL-adressen til tilbagekald fra Skift og de objekttyper, der skal synkroniseres.

Hvis du vil registrere og aktivere integration af arbejdsstyrken, skal du udføre følgende trin:

Trin 4a: Registrer integration af arbejdsstyrken i din lejer

Du skal være global administrator for at kunne udføre dette trin.

Brug API'en Create workforceIntegration til at registrere din integration af arbejdsstyrken i din lejer.

Her er et eksempel på en anmodning.

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

Se følgende tabel for at få flere oplysninger. Du kan få mere at vide under ressourcetype for workforceIntegration.

Egenskab Flere oplysninger
apiVersion API-version for URL-adressen til tilbagekald. Din grundlæggende URL-adresse består af url-egenskaben og denne egenskab.
kryptering Angiv protokollen til sharedSecret. Værdien for hemmeligheden skal være nøjagtigt 64 tegn.

Brug hemmeligheden til at dekryptere de krypterede JSON-nyttedata, der sendes til connectorens slutpunkt fra Skifts. Nyttedata krypteres ved hjælp af AES-256-CBC-HMAC-SHA256. Din app bør bevare denne hemmelighed på en sikker måde. For eksempel i en key vault.
supportedEnheder Angiv de Shifts-enheder, som connectoren skal understøtte til synkronisering. Skift kalder slutpunktet /opdateringen for din connector, når en af disse objekter ændres, så du kan godkende eller afvise ændringen. Du kan se en liste over de mulige værdier under ressourcetypen workforceIntegration

Seddel Denne liste er en udtryksfuld optælling. Du skal bruge anmodningsheaderen Prefer: include-unknown-enum-members til at hente alle værdierne.
eligibilityFilteringEnabledEntities Bemærk! Fra og med oktober 2024 understøttes dette slutpunkt kun i betaversionen af Microsoft Graph API.

Angiv de Shifts-enheder, du vil oprette forbindelse til, som understøtter berettigelsesfiltrering. De mulige værdier er:
  • none, tom liste
  • SwapRequests: Skifter kalder connectorens /læse-slutpunkt for at få en filtreret liste over skiftehold, som en bruger kan vælge imellem til en swapanmodning.
  • TimeOffReasons: Skifter kalder connectorens /læse-slutpunkt for at få en filtreret liste over fridagsårsager, som en bruger kan vælge imellem, når vedkommende anmoder om fri.
Seddel Denne liste er en udtryksfuld optælling. Du skal bruge anmodningsheaderen Prefer: include-unknown-enum-members til at hente alle værdierne.
URL-adresse URL-adressen til integration af arbejdsstyrken for tilbagekald fra skift. Din grundlæggende URL-adresse består af denne egenskab og egenskaben apiVerson .

Trin 4b: Aktivér integration af arbejdsstyrken for dine teamplaner

Aktivér integration af din arbejdsstyrke efter de tidsplaner, du vil administrere. Det gør du ved at bruge API'en Opret eller erstat tidsplan til at oprette eller opdatere tidsplanen for dine teams.

Her er et eksempel på en anmodning.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}
  • Angiv det workforceIntegrationId, der blev genereret, da du registrerede medarbejderintegrationen.
  • Du kan maksimalt aktivere én integration af arbejdsstyrken efter en tidsplan. Hvis du medtager mere end én workforceIntegrationId i anmodningen, bruges den første.

Fejlfinding

Stik

Hvad sker der, når connectoren besvarer en anmodning fra Skifts, hvis den returnerer en anden svarkode end 200? Gør det en forskel, om den returnerer en anden status end 200 i svarteksten?

Der er en forskel mellem disse to scenarier.

  • Hvis connectoren returnerer en anden svarkode end 200, forsøger Skift at prøve slutpunkterne /read og /update flere gange. I sidste ende viser Shifts "Noget gik galt. Konfigurationen af medarbejderintegrationen i teamet har svaret med ugyldige data." fejlmeddelelse.
  • Hvis connectoren returnerer en anden status end 200 i svarteksten, viser Shifts "Noget gik galt. Vi beklager, men ændringen kunne ikke fuldføres", fejlmeddelelse og stopper forsøg på at udføre slutpunkterne igen.

Hvad sker der, hvis connectoren returnerer ugyldige data i svarteksten?

Skifter forsøger at prøve slutpunkterne /read og /update flere gange. I sidste ende viser Shifts "Noget gik galt. Den medarbejderintegration, der er konfigureret i teamet, har svaret med ugyldige data." fejlmeddelelse.

Hvordan gør jeg identificere, om anmodningen oprindeligt blev fremsat i Skift eller i WFM system for at forhindre en uendelig løkke?

Føj headeren X-MS-WFMPassthrough: workforceIntegratonId til alle kald til skrivning og opdatering for at identificere/ignorere de ændringer, der udløses af connectoren. Denne header bruges til at angive, at anmodningen foretages på grund af et tidligere kald, der blev foretaget af connectoren til Graph API for at synkronisere data fra dit WFM system til Skifts.

Registrering af integration af arbejdsstyrke

Jeg registrerede medarbejderintegrationen og angav "eligibilityFilteringEnabledEntities", herunder "SwapRequest, OfferShiftRequest og TimeOffReason", men svarteksten viser ikke listen "eligibilityFilteringEnabledEntities".

Filtrering af berettigelse understøttes i øjeblikket via slutpunktet https://graph.microsoft.com/beta og ikke slutpunktet https://graph.microsoft.com/v1 .

Jeg registrerede integration af arbejdsstyrken og tilføjede "supportedEntities", men modtager et svar på 400 Bad Request og en "Ugyldig nyttedata: Anmodet værdi "skift, ...." blev ikke fundet."

Sørg for, at alle Shifts-enheder på supportedEntities listens brødtekst starter med et stort bogstav. Det kunne f.eks. være "supportedEntities":"Shift,SwapRequest,OpenShift".

Jeg registrerede medarbejderintegrationen og implementerede /connect-, /update- og /read-slutpunkterne, men webhooket fungerer ikke.

Sørg for, at din medarbejderintegration er aktiveret for din teamplan. Kontrollér desuden, at egenskaberne url og apiVersion er korrekte.

Slutpunktreference

Bøn

ConnectRequest

Egenskab Type Beskrivelse
tenantId String Id for lejeren til integration af arbejdsstyrken
userId String Id for brugeren til integration af arbejdsstyrken 
{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Egenskab Type Beskrivelse
Anmodninger WfiRequest-samling Liste over WfiRequests 
{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

Antal elementer i en anmodning:

  • I de fleste tilfælde har en anmodning ét element.
  • Nogle anmodninger, f.eks. godkendelser af swapskiftanmodninger, har fem elementer: én PUT-swapanmodning, to DELETE-skift (eksisterende skift) og to POST-skift (nye skift).

WfiRequest

Egenskab Type Beskrivelse
id String Id for enheden
metode String Den metode, der blev aktiveret for elementet. F.eks. POST, PUT, GET, DELETE.
URL-adresse String Angiver typen af objekt- og handlingsoplysninger.
Overskrifter WfiRequestHeader Overskrifter
legeme ShiftsEntity Brødteksten i den enhed, der er relateret til anmodningen.
For POST/teams/{teamId}/update
Egenskab Type Beskrivelse
id String Id for enheden
metode String POST for at oprette et objekt, PUT opdatere et objekt og DELETE slette et objekt.
URL-adresse String Formatet er /{EntityType}/{EntityId}. De mulige værdier for {EntityType} er shifts, swapRequests, timeoffReasons, openshifts, openshiftrequests, offershiftrequests, , timesoff, timeOffRequests. Det kunne f.eks. være /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
header WfiRequestHeader Sidehoved
legeme ShiftsEntity Skal stemme overens {EntityType} i url-egenskaben . Brug skift,swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Det kunne f.eks. være /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
For POST /teams/{teamsId}/read
Egenskab Type Beskrivelse
id String Id for enheden
metode String Er altid GET.
URL-adresse String
  • TimeOffReasons: Formatet er /users/{userId}/timeOffReasons?requestType=TimeOffReason. Det kunne f.eks. være /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason.
  • SwapRequest: Formatet er /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Det kunne f.eks. være shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
header WfiRequestHeader Sidehoved
legeme ShiftsEntity Er altid null.

WfiRequestHeader

Egenskab Type Beskrivelse
X-MS-Transaction-ID String Transaktions-id
X-MS-Expires Streng (DateTime) Udløbsdato for transaktion

X-MS-WFMPassthrough: workforceIntegratonId medtages ikke i WfiRequestHeader. Den skal udtrækkes fra HttpRequest.

Svar

WfiResponseContainer

Egenskab Type Beskrivelse
Svar WfiResponse-samling Liste over WfiResponses 
{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Egenskab Type Beskrivelse
id String Id for enheden
status String Resultatet af handlingen
legeme WfiResponseBody WfiResponseBody

WfiResponseBody

Egenskab Type Beskrivelse
eTag String eTag
fejl WfiResponseError Detaljer om fejlen
data String De ønskede data (for læseanmodninger)

WfiResponseError

Egenskab Type Beskrivelse
kodeks String Fejlkode
budskab String Fejlmeddelelse