Luo mukautettu integrointi, jotta voit synkronoida työvoimanhallintajärjestelmäsi vuorojen avulla

• Koskee seuraavia::

  Microsoft Teams, Microsoft 365 for frontline workers

Yleiskatsaus

Integroi työvuorot, Microsoft Teamsin aikataulunhallintasovellus, työvoimanhallintajärjestelmäsi (WFM) kanssa. Tämän integraation avulla etulinjan työntekijät voivat tarkastella ja hallita aikataulujaan suoraan Vuorot-kohdassa.

Tässä artikkelissa kerrotaan, miten voit luoda liittimen Microsoft Graph -ohjelmointirajapinnan avulla tämän integroinnin helpottamiseksi.

Voit määrittää integroinnin joko yksisuuntaiselle tietojen synkronoinnille tai kaksisuuntaiseen tietojen synkronointiin.

• Yksisuuntainen synkronointi (WFM järjestelmä vuoroihin): Ajoita tässä määrityksessä WFM järjestelmän tiedot synkronoidaan työvuoroihin. Liitin lukee WFM järjestelmän tiedot ja kirjoittaa ne Shiftsiin. Käyttäjien vuoroihin tekemät muutokset eivät kuitenkaan näy takaisin WFM järjestelmässäsi.

• Kaksisuuntainen synkronointi (WFM järjestelmä ja työvuorot): Tämä asetus sallii kaksisuuntaisen synkronoinnin. WFM järjestelmän ajoitetut tiedot synkronoidaan vuoroihin ja käyttäjien vuoroissa tekemät muutokset synkronoidaan takaisin WFM järjestelmääsi. Liitin vahvistaa ja hyväksyy muutokset, jotka käyttäjät tekevät vuoroissa WFM järjestelmän pakottamien liiketoimintasääntöjen mukaisesti, ennen kuin muutokset kirjoitetaan työvuoroihin.

Huomautus

Jos käytät UKG Pro WFM-, Blue Yonder WFM- tai Reflexis-WFM, voit myös integroida vaihtovuorot WFM järjestelmään hallitun liittimen avulla. Lisätietoja on artikkelissa Vaihtoliittimet.

Tässä artikkelissa käytetty terminologia

Termi	Kuvaus
liitin	Sovellus, joka synkronoi ajoitetut tiedot WFM järjestelmän ja työvuorojen välillä.
työvoiman integrointi	Entiteetti, joka määrittää tietoliikenteen salausmenetelmän, liittimesi takaisinkutsun URL-osoitteen ja synkronoitavat Vaihto-entiteetit.

Alkuvalmistelut

Ennakkovaatimukset

• Selvitä, mitä tietoja haluat synkronoida yrityksesi tarpeiden mukaan.
• Tutustu Microsoftin käyttäjätietoympäristö todentamisen ja valtuutuksen käsitteisiin. Katso Todentamisen ja valtuutuksen perusteet.
• Hallinta roolit vaaditaan:
  • Vähintään pilvisovelluksen järjestelmänvalvoja rekisteröimään sovelluksen Microsoft Entra -hallintakeskus
  • Yleinen järjestelmänvalvoja rekisteröimään työvoiman integroinnin

Tutustu integrointiprosessiin

Tässä on yleiskatsaus integroinnin vaiheista. Tarkastele näitä tietoja saadaksesi käsityksen kokonaisprosessista, mukaan lukien siitä, kuka suorittaa kunkin vaiheen.

Vaihe	Yksisuuntainen synkronointi	Kaksisuuntainen synkronointi	Kuka suorittaa tämän vaiheen?
1	Luo liitin: Vaihe 1a: WFM järjestelmän vuoroissa tehtyjen muutosten synkronoiminen Toteuta /connect-päätepiste Toteuta /päivitä päätepiste ja määritä työvuorot vain luku -tilaan Vaihe 1b: Tietojen synkronointi WFM järjestelmästä työvuoroihin	Luo liitin: Vaihe 1a: WFM järjestelmän vuoroissa tehtyjen muutosten synkronoiminen Toteuta /connect-päätepiste Toteuta /päivitä päätepiste Vaihe 1b: Tietojen synkronointi WFM järjestelmästä työvuoroihin	Developer
2	Sovelluksen rekisteröiminen Microsoft Entra -hallintakeskus	Sovelluksen rekisteröiminen Microsoft Entra -hallintakeskus	Tili, joka on vähintään pilvisovelluksen järjestelmänvalvoja
3	Tiimien ja aikataulujen luominen synkronointia varten	Tiimien ja aikataulujen luominen synkronointia varten	Kehittäjä tai Teams-järjestelmänvalvoja
4	Rekisteröi ja ota käyttöön työvoiman integrointi: Vaihe 4a: Rekisteröi työvoiman integrointi vuokraajaan Vaihe 4b: Ota käyttöön työvoiman integrointi tiimisi aikatauluissa	Rekisteröi ja ota käyttöön työvoiman integrointi: Vaihe 4a: Rekisteröi työvoiman integrointi vuokraajaan Vaihe 4b: Ota käyttöön työvoiman integrointi tiimisi aikatauluissa	Vaihe 4a: Yleinen järjestelmänvalvoja Vaihe 4b: Kehittäjä

Vaihe 1: Liittimen luominen

Voit luoda liittimen suorittamalla seuraavat vaiheet:

• Vaihe 1a: WFM järjestelmän vuoroissa tehtyjen muutosten synkronoiminen
• Vaihe 1b: tietojen synkronointi WFM järjestelmästä työvuoroihin

Vaihe 1a: WFM järjestelmän vuoroissa tehtyjen muutosten synkronoiminen

Jotta voit määrittää liittimesi vastaanottamaan ja käsittelemään työvuorojen pyyntöjä, sinun on toteutettava seuraavat päätepisteet:

• /connect (pakollinen)
• /update (pakollinen)
• /read (valinnainen)

Perus-URL-osoitteen ja päätepisteen URL-osoitteiden määrittäminen

Perus-URL (webhook) on {url}/v{apiVersion}, jossa URL jaapiVersion ovat ominaisuuksia, jotka määrität workforceIntegration-objektissa, kun rekisteröit työvoiman integroinnin.

Päätepisteen URL-osoitteiden suhteelliset polut ovat seuraavat:

• /yhdistää: /connect
• /päivittää: /teams/{teamid}/update
• /lukea: /teams/{teamid}/read

Jos URL-osoite on https://contosoconnector.com/wfi esimerkiksi ja apiVersion on 1:

• Url-perusosoite on https://contosoconnector/com/wfi/v1.
• /connect-päätepiste on https://contosoconnector/wfi/v1/connect.
• /update-päätepiste on https://contosoconnector/wfi/v1/teams/{teamid}/update.
• /read-päätepiste on https://contosoconnector/wfi/v1/teams/{teamid}/read.

Salaus

Kaikki pyynnöt salataan AES-256-CBC-HMAC-SHA256:n avulla. Määrität jaetun salaisen koodin avaimen , kun rekisteröit työvoiman integroinnin. Työvuoroihin lähetettyjä vastauksia ei pidä salata.

Päätepisteet

POST /connect

Shifts kutsuu tätä päätepistettä testatakseen yhteyttä, kun rekisteröit työvoiman integroinnin. Onnistumisvastaus palautetaan vain, jos tämä päätepiste palauttaa HTTP-vastauksen 200 OK .

Esimerkki

Pyytää
Yhdistäpyyntö

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

Vastaus
Palauta HTTP 200 OK

POST /teams/{teamid}/update

Vuorot kutsuvat tätä päätepistettä saadakseen hyväksynnän, kun Shifts-entiteettiin tehdään muutos aikataulussa , joka on otettu käyttöön työvoiman integroinnille. Jos tämä päätepiste hyväksyy pyynnön, muutos tallennetaan työvuoroihin.

Koska WFM järjestelmä on tietuejärjestelmä, kun liitin vastaanottaa pyynnön tähän päätepisteeseen, sen pitäisi ensin yrittää tehdä muutos WFM järjestelmässä. Jos muutos onnistuu, palauta onnistuminen. Muussa tapauksessa palautusvirhe.

Shifts kutsuu tätä päätepistettä jokaiselle muutokselle (mukaan lukien liittimestä/WFM järjestelmän aloittamille muutoksille). Jos yhdistin lähetti päivityksen Shiftsiin Graph-ohjelmointirajapinnan avulla ja lisäsi X-MS-WFMPassthrough: workforceIntegratonId otsikon, tähän päätepisteeseen tulevalla pyynnöllä on sama otsikko, jonka avulla voit tunnistaa ja käsitellä näitä pyyntöjä asianmukaisesti. Voit esimerkiksi palauttaa onnistumisen tekemättä samaa muutosta WFM järjestelmään kuin se olisi tarpeetonta ja saattaa aiheuttaa liittimen jumiutumisen loputtomaan silmukkaan.

Seuraavassa kaaviossa esitetään tietojen kulku.

Huomautus

Lisätietoja pyyntö- ja vastausmalleista on tämän artikkelin päätepisteen viiteosionWfiRequest-kohdassa.

Palautusvastauskoodi
Integroinnin vastauksella, virhe mukaan lukien, on oltava HTTP-vastauskoodi 200 OK. Vastauksen leipätekstissä on oltava tila ja virhesanoma, jotka vastaavat asianmukaista alikutsuvirhetilaa. Mitä tahansa muun integraation vastausta kuin 200 OK käsitellään virheenä ja palautetaan kutsujalle (asiakas tai Microsoft Graph).

Jos haluat määrittää yksisuuntaisen synkronoinnin, tee vuoroista vain luku -tilassa

Yksisuuntaista synkronointia varten työvuorot on määritettävä vain luku -tilaan, jotta käyttäjät eivät voi tehdä muutoksia työvuoroihin. Jos haluat tehdä työvuoroista vain luku -muotoisia, palauta virhevastaus kaikille vuorojen pyynnöille.

Jos haluat esimerkiksi estää käyttäjiä tekemästä muutoksia aikataulun vuoroihin, tämän päätepisteen on palautettava virhevastaus aina, kun se saa entiteettiä shift koskevan pyynnön.

Esimerkki

Pyytää
WfiRequestContainer

Seuraavassa esimerkissä esitetään Shiftsin pyyntö, jossa kysytään, voidaanko vuoro, jonka tunnus on SHFT_12345678-1234-1234-12344-1234567890ab ja jonka ominaisuudet on lueteltu leipätekstissä, tallentaa vuoroihin. Tämä pyyntö käynnistyi, kun käyttäjä luo vuoroja.

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

Vastaus
WfiResponse

Onnistui: Palauta HTTP 200 OK

Tässä esimerkissä näytetään palautettu vastaus, jos päätepiste hyväksyi pyynnön. Tässä skenaariossa vuoro tallennetaan työvuoroihin, ja käyttäjä näkee vuoron aikataulussa.

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

Virhe: palauta HTTP 200 OK

Tässä esimerkissä näytetään palautettu vastaus, jos päätepiste hylkäsi pyynnön. Tässä skenaariossa käyttäjä saa Vuorot-kohdassa virhesanoman "Vaihtoa ei voitu lisätä".

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

Tämä päätepiste käsittelee työvuorojen pyynnöt, jotka koskevat kelvollisia vapaa-ajan syitä tai kelvollisia vuoroja käyttäjän vaihtopyyntöjä varten.

Huomautus

Lokakuusta 2024 alkaen tätä päätepistettä tuetaan vain Microsoft Graph -ohjelmointirajapinnan beetaversiossa. Sinun on myös määritettävä arvot kelpoisuusasetukselle KelpoisuusSuodatusEnabledEntiteetit , kun rekisteröit työvoiman integroinnin.

Seuraavassa kaaviossa esitetään tietojen kulku.

Palautusvastauskoodi
Integroinnin vastauksella, virhe mukaan lukien, on oltava HTTP-vastauskoodi 200 OK. Vastauksen leipätekstissä on oltava tila ja virhesanoma, jotka vastaavat asianmukaista alikutsun virhetilaa. Mitä tahansa muun integraation vastausta kuin 200 OK käsitellään virheenä ja palautetaan kutsujalle (asiakas tai Microsoft Graph).

Esimerkki: TimeOffReason

Pyytää

Seuraavassa esimerkissä esitetään Shifts-pyyntö, jossa kysytään, mihin vapaa-aikaan käyttäjä (käyttäjätunnus aa162a04-bec6-4b81-ba99-96caa7b2b24d) on oikeutettu. Tämä pyyntö käynnistyi, kun käyttäjä pyytää vapaa-aikaa työvuoroissa.

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

Vastaus
Onnistui: Palauta HTTP 200 OK

Seuraava vastaus näyttää, että käyttäjän kelvolliset vapaa-ajan syytunnukset ovat "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" ja "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". Tässä skenaariossa käyttäjä näkee vastaavat aika-vapaa-ajan syyt, joista valita vuoroissa.

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

Virhe: palauta HTTP 200 OK

Tässä esimerkissä palautetaan virhevastaus, koska liitin ei voinut muodostaa yhteyttä WFM järjestelmään hakeakseen käyttäjän vapaa-ajan syitä.

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

Esimerkki: SwapRequest

Pyytää

Seuraavassa esimerkissä esitetään Shiftsin pyyntö, jossa kysytään, mitkä vuorot ovat oikeutettuja vaihtoon sellaisen vuoron kanssa, jonka tunnus on SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 välillä 2024–202410-01T04:00:00.000000Z ja 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"
    }
  ]
}

Vastaus
Onnistui: Palauta HTTP 200 OK

Seuraava vastaus osoittaa, että vuoro voidaan vaihtaa vuoroon, jonka tunnus on 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, 
      } 
    }
  ]
}

Virhe: palauta HTTP 200 OK

Tässä esimerkissä palautetaan virhevastaus, koska liitin ei voinut muodostaa yhteyttä WFM järjestelmään, jotta käyttäjälle voidaan hakea hyväksyttävät vuorot vaihtopyyntöä varten.

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

Vaihe 1b: tietojen synkronointi WFM järjestelmästä työvuoroihin

Käytä Shifts-ohjelmointirajapintoja Microsoft Graphissa aikataulutietojen lukemiseen WFM järjestelmästä ja tietojen kirjoittamiseen Shiftsiin.

Jos haluat esimerkiksi lisätä vuoron Vuorot-kohtaan, käytä Luo vuoro -ohjelmointirajapintaa.

Katso Microsoft Graph -ohjelmointirajapinnan v1.0-viittaus shifts-ohjelmointirajapinnoista, jotka on lueteltu vuorojen hallinnassa.

Huomautus

Ylätunniste MS-APP-ACTS-AS on pakollinen pyynnöissä, ja sen on sisällettävä sen käyttäjän tunnus (GUID), jonka puolesta sovelluksesi toimii. Suosittelemme, että käytät aikataulua päivitettäessä ryhmän omistajan käyttäjätunnusta.

Seuraavassa kaaviossa esitetään tietojen kulku.

Ensimmäinen synkronointi

Ensimmäisen synkronoinnin yhteydessä liittimen on luettava WFM järjestelmän tiedot ja kirjoitettava tiedot Shiftsiin. Suosittelemme, että synkronoit kahden viikon tulevat tiedot.

Ensimmäisen synkronoinnin jälkeen

Ensimmäisen synkronoinnin jälkeen voit valita seuraavaa:

• Päivitä työvuorot synkronisesti WFM järjestelmän muutoksilla: Lähetä päivitys työvuoroihin jokaisesta WFM järjestelmässä tehdystä muutoksesta.

• Päivitä työvuorot asynkronisesti WFM järjestelmän muutoksilla: Suorita jaksoittainen synkronointi kirjoittamalla kaikki muutokset, jotka tapahtuivat WFM järjestelmässä tietyn ajanjakson aikana (esimerkiksi 10 minuuttia) työvuoroihin.

  Kaikki vaihtojen kirjoitustoiminnot, mukaan lukien liittimen aloittamat kirjoitustoiminnot, käynnistävät kutsun liittimen /update-päätepisteeseen. Suosittelemme, että X-MS-WFMPassthrough: workforceIntegratonId sisällytät otsikon kaikkiin kirjoituskutsuihin, jotta liitin tunnistaa ja käsittelee ne asianmukaisesti. Jos WFM järjestelmäsi on esimerkiksi aloittanut muutoksen, hyväksy se käyttämättä päivitystä WFM järjestelmään.

  Huomautus

  Jos olet määrittämässä liitintä tietojen kaksisuuntaista synkronointia varten WFM järjestelmän ja vaihtojen välillä, jätä vuoroista aloitetut muutokset pois jaksottaisessa synkronoinnissa. Nämä muutokset on jo kirjoitettu Vuorot-kohdassa.

Vaihe 2: Sovelluksen rekisteröiminen Microsoft Entra -hallintakeskus

Näiden ohjeiden avulla voit rekisteröidä sovelluksen liittimellesi Microsoftin käyttäjätietoympäristö, määrittää sovelluksen käyttöoikeudet Microsoft Graphin käyttämiseen ja hankkia käyttöoikeustietueen.

1. Kirjaudu Microsoft Entra -hallintakeskus vähintään pilvipalvelusovelluksen järjestelmänvalvojana.

2. Rekisteröi sovelluksesi. Katso ohjeet kohdasta Sovelluksen rekisteröiminen Microsoftin käyttäjätietoympäristö.

3. Määritä Schedule.ReadWrite.Kaikkisovelluksen käyttöoikeudet sovellukselle vain sovelluskäyttöä varten ja hanki käyttöoikeustietue.

   Vaiheittaiset ohjeet ovat kohdassa Käyttöoikeuksien hankkiminen ilman käyttäjää.

   Käyttöoikeustietue varmistaa, että sovelluksella on oikeus kutsua Microsoft Graphia käyttämällä omia käyttäjätietojaanSchedule.ReadWrite.All-käyttöoikeudella . Sen on oltava mukana pyyntöjen Valtuutus-otsikossa.

Vaihe 3: Tiimien ja aikataulujen luominen synkronointia varten

Määritä Teams-tiimit, jotka haluat synkronoida. Voit käyttää olemassa olevia tiimejä tai luoda uusia tiimejä.

1. Määritä Teamsiin tiimejä vastaamaan WFM järjestelmän tiimejä ja sijainteja. Varmista, että lisäät kuhunkin tiimiin seuraavat henkilöt:

   • Frontlinen johtajat tiimin omistajina. Varmista, että lisäät käyttäjän ylätunnisteeseen MS-APP-ACTS-AS kunkin tiimin omistajaksi.
   • Etulinjan työntekijät tiimin jäseninä.

2. Luo aikataulu vuoroissa kullekin tiimille. Lisätietoja on artikkelissa Aikataulun luominen tai korvaaminen.

3. Lisää aikatauluryhmiä aikatauluun kussakin tiimissä. Aikatauluryhmiä käytetään työntekijöiden ryhmittelyyn työryhmän yleisten ominaisuuksien perusteella. Aikatauluryhmät voivat olla esimerkiksi osastoja tai työtyyppejä. Lisätietoja on artikkelissa schedulingGroup-resurssityyppi.

4. Lisää työntekijöitä kuhunkin aikatauluryhmään. Lisätietoja on artikkelissa SchedulingGroup-kohteen korvaaminen.

Huomautus

Voit myös käyttää Teams-hallintakeskusta tiimien määrittämiseen ja vuorojen käyttöönottoon tiimeissä. Lisätietoja on ohjeaiheissa:

• Ota käyttöön etulinjan dynaamisia tiimejä mittakaavassa
• Ota vuorot käyttöön etulinjan tiimeissä suuressa mittakaavassa

Vaihe 4: Rekisteröi ja mahdollista työvoiman integrointi

Työvoiman integrointi määrittää vaihtojen ja liittimen välisen tietoliikenteen salausasetukset, vaihtojen vastakutsujen URL-osoitteen ja synkronoitavien entiteettien tyypit.

Voit rekisteröidä työvoiman ja ottaa sen käyttöön suorittamalla seuraavat vaiheet:

• Vaihe 4a: Työvoiman integroinnin rekisteröiminen
• Vaihe 4b: Ota käyttöön työvoiman integrointi tiimisi aikatauluissa

Vaihe 4a: Rekisteröi työvoiman integrointi vuokraajaan

Sinun on oltava yleinen järjestelmänvalvoja, jotta voit suorittaa tämän vaiheen.

Rekisteröi työvoiman integrointi vuokraajaasi Käyttämällä Create workforceIntegration-ohjelmointirajapintaa .

Tässä on esimerkki pyynnöstä.

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

Lisätietoja on seuraavassa taulukossa. Lisätietoja on artikkelissa workforceIntegration-resurssityyppi.

Ominaisuus	Lisätietoja
apiVersion	Takaisinkutsun URL-osoitteen ohjelmointirajapinnan versio. Url-perusosoite sisältää URL-ominaisuuden ja tämän ominaisuuden.
salaus	Aseta protokollan arvoksi sharedSecret. Salaisen koodin arvon on oltava täsmälleen 64 merkkiä pitkä. Salaisen koodin avulla voit purkaa salattujen JSON-tietojen salauksen, jotka lähetetään liittimen päätepisteeseen Shifts-sovelluksesta. Tiedot salataan AES-256-CBC-HMAC-SHA256:lla. Sovelluksesi tulisi turvallisesti pitää tämän salaisen koodin. Esimerkiksi Key Vaultissa.
tuetut entiteetit	Määritä Shifts-entiteetit, joita haluat liittimen tukevan synkronointia varten. Shifts kutsuu liittimen /update-päätepistettä , kun jokin näistä entiteeteistä muuttuu, jotta voit hyväksyä tai hylätä muutoksen. Katso luettelo mahdollisista arvoista kohdasta WorkforceIntegration-resurssityyppi Muistiinpano Tämä luettelo on kehittyvä luettelointi. Sinun on käytettävä Prefer: include-unknown-enum-members pyynnön otsikkoa saadaksesi kaikki arvot.
eligibilityFilteringEnabledEntities	Huomautus: Lokakuusta 2024 alkaen tätä päätepistettä tuetaan vain Microsoft Graph -ohjelmointirajapinnan beetaversiossa. Määritä Shifts-entiteetit, joita haluat yhdistimen tukevan kelpoisuussuodatusta. Mahdollisia arvoja ovat: none: Tyhjä luettelo SwapRequests: Työvuorot kutsuvat liittimen /read-päätepistettä saadakseen suodatetun luettelon vuoroista, joista käyttäjä voi valita vaihtopyyntöä varten. TimeOffReasons: Työvuorot kutsuvat liittimen /read-päätepistettä saadakseen suodatetun luettelon aikakatkaisusyistä, joista käyttäjä voi valita, kun hän pyytää vapaa-aikaa. Muistiinpano Tämä luettelo on kehittyvä luettelointi. Sinun on käytettävä Prefer: include-unknown-enum-members pyynnön otsikkoa saadaksesi kaikki arvot.
URL	Työvuorojen vastakutsujen työvoimaintegroinnin URL-osoite. Perus-URL koostuu tästä ominaisuudesta ja apiVerson-ominaisuudesta.

Vaihe 4b: Ota käyttöön työvoiman integrointi tiimisi aikatauluissa

Ota työvoiman integrointi käyttöön niiden aikataulujen mukaisesti, joita haluat hallita. Voit tehdä tämän luomalla tai korvaamalla aikataulun ohjelmointirajapinnan luomalla tai päivittämällä tiimiesi aikataulun.

Tässä on esimerkki pyynnöstä.

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

• Määritä workforceIntegrationId, joka luotiin, kun rekisteröit työvoiman integroinnin.
• Voit ottaa käyttöön enintään yhden työvoiman integroinnin aikataulun mukaisesti. Jos sisällytät pyyntöön useamman kuin yhden workforceIntegrationId-tunnuksen, käytetään ensimmäistä.

Vianmääritys

Liitin

Kun liitin vastaa Työvuorojen pyyntöön, mitä tapahtuu, jos se palauttaa muun vastauskoodin kuin 200? Onko sillä merkitystä, jos se palauttaa vastausrungossa muun kuin 200 tilan?

Näiden kahden skenaarion välillä on ero.

• Jos liitin palauttaa muun kuin 200 vastauskoodin, vaihtovuorot yrittävät käyttää päätepisteitä /read ja /update useita kertoja. Lopulta Shifts näyttää "Jokin meni vikaan. Tiimisi työvoiman integroinnin määritys on vastannut virheellisillä tiedoilla." virhesanoma.
• Jos liitin palauttaa vastaustekstissä muun kuin 200 tilan, Shifts näyttää tekstin "Jokin meni vikaan. Muutosta ei voitu tehdä", virhesanoma päätepisteiden uudelleenyritysten lopettamisesta.

Mitä tapahtuu, jos liitin palauttaa virheellisiä tietoja vastauksen runkoon?

Vuorot yrittävät uudelleen päätepisteitä /read ja /update useita kertoja. Lopulta Shifts näyttää "Jokin meni vikaan. Tiimillesi määritetty työvoiman integrointi on vastannut virheellisillä tiedoilla." virhesanoma.

Ohjevalikko selvittää, esitettiinkö pyyntö alun perin Shifts- vai WFM-järjestelmässä loputtoman silmukan estämiseksi?

X-MS-WFMPassthrough: workforceIntegratonId Lisää ylätunniste kaikkiin kirjoitus- ja päivityskutsuihin, jotta voit tunnistaa tai ohittaa liittimen käynnistämät muutokset. Tätä otsikkoa käytetään ilmaisemaan, että pyyntö on tehty, koska yhdistin teki aiemmin Graph-ohjelmointirajapintaan kutsun tietojen synkronoimiseksi WFM järjestelmästä vaihtoihin.

Työvoiman integroinnin rekisteröinti

Rekisteröin työvoiman integroinnin ja määritin määrityksen "eligibilityFilteringEnabledEntities", mukaan lukien "SwapRequest, OfferShiftRequest ja TimeOffReason", mutta vastauksen leipäteksti ei näytä "eligibilityFilteringEnabledEntities"-luetteloa.

Kelpoisuuden suodatusta tuetaan tällä hetkellä päätepisteen, ei https://graph.microsoft.com/v1 päätepisteen kauttahttps://graph.microsoft.com/beta.

Rekisteröin työvoiman integroinnin ja lisäsin "tuetut entiteetit", mutta sain 400 virheellisen pyynnön vastauksen ja "Virheellinen hyötykuorma: Pyydetty arvo vaihto, .... " ei löytynyt." viesti

Varmista, että luettelopyynnön leipätekstin supportedEntities jokainen Shifts-entiteetti alkaa isolla kirjaimella. Esimerkiksi "supportedEntities":"Shift,SwapRequest,OpenShift".

Rekisteröin työvoiman integroinnin ja toteutin /connect-, /update- ja /read-päätepisteet, mutta webhook ei toimi.

Varmista, että työvoiman integrointi on otettu käyttöön tiimisi aikataulua varten. Tarkista lisäksi, että URL- ja apiVersion-ominaisuudet ovat oikein.

Päätepisteen viittaus

Pyytää

Yhdistäpyyntö

Ominaisuus	Kirjoita	Kuvaus
tenantId	Merkkijono	Työvoiman integroinnin vuokraajan tunnus
userId	Merkkijono	Käyttäjän tunnus työvoiman integrointia varten

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

WfiRequestContainer

Ominaisuus	Kirjoita	Kuvaus
Pyyntöjä	WfiRequest-kokoelma	WfiRequest-luettelo

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

Pyynnön elementtien määrä:

• Useimmissa tapauksissa pyynnöllä on yksi elementti.
• Joissakin pyynnöissä, kuten vaihtovuoropyynnön hyväksynnöissä, on viisi elementtiä: yksi PUT-vaihtopyyntö, kaksi DELETE-vuoroa (olemassa olevat vuorot) ja kaksi POST-vuoroa (uudet vuorot).

WfiRequest

Ominaisuus	Kirjoita	Kuvaus
id	Merkkijono	Entiteetin tunnus
menetelmä	Merkkijono	Kohteessa käynnistetty menetelmä. Esimerkiksi , POST, PUT, GET, DELETE.
URL	Merkkijono	Ilmaisee entiteetin tyypin ja toiminnon tiedot.
Otsikot	WfiRequestHeader	Otsikot
keho	ShiftsEntity	Pyyntöön liittyvän entiteetin runko.

POST/teams/{teamId}/update

Ominaisuus	Kirjoita	Kuvaus
id	Merkkijono	Entiteetin tunnus
menetelmä	Merkkijono	POST entiteetin luomista, PUT entiteetin päivittämistä ja DELETE entiteetin poistamista.
URL	Merkkijono	Muoto on /{EntityType}/{EntityId}. Mahdollisia arvoja ovat , , , , openshifts, openshiftrequests, offershiftrequests, , timesoff. timeOffRequeststimeoffReasonsswapRequestsshifts{EntityType} Esimerkiksi /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
otsikko	WfiRequestHeader	Otsikko
keho	ShiftsEntity	Url-ominaisuuden on vastattava toisiaan{EntityType}. Käytä yhtä vuorosta, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Esimerkiksi /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.

POST/teams/{teamsId}/read

Ominaisuus	Kirjoita	Kuvaus
id	Merkkijono	Entiteetin tunnus
menetelmä	Merkkijono	On aina GET.
URL	Merkkijono	TimeOffReasons: Muoto on /users/{userId}/timeOffReasons?requestType=TimeOffReason. Esimerkiksi /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason. SwapRequest: Muoto on /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Esimerkiksi shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
otsikko	WfiRequestHeader	Otsikko
keho	ShiftsEntity	On aina null.

WfiRequestHeader

Ominaisuus	Kirjoita	Kuvaus
X-MS-Transaction-ID	Merkkijono	Tapahtuman tunnus
X-MS-Expires	Merkkijono (DateTime)	Tapahtuman vanhentumispäivämäärä ja aika

X-MS-WFMPassthrough: workforceIntegratonId ei sisälly WfiRequestHeader-tiedostoon. Se tulee poimia HttpRequest-pyynnöstä.

Vastaus

WfiResponseContainer

Ominaisuus	Kirjoita	Kuvaus
Vastaukset	WfiResponse-kokoelma	WfiResponses-luettelo

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

WfiResponse

Ominaisuus	Kirjoita	Kuvaus
id	Merkkijono	Entiteetin tunnus
tila	Merkkijono	Toiminnon tulos
keho	WfiResponseBody	WfiResponseBody

WfiResponseBody

Ominaisuus	Kirjoita	Kuvaus
eTag	Merkkijono	eTag
virhe	WfiResponseError	Virheen tiedot
data	Merkkijono	Pyydetyt tiedot (lukupyyntöjä varten)

WfiResponseError

Ominaisuus	Kirjoita	Kuvaus
koodi	Merkkijono	Virhekoodi
viesti	Merkkijono	Virheilmoitus

Aiheeseen liittyviä artikkeleita

• Vuorot etulinjan organisaatiolle
• Vuorot-yhdistimet