Creare un'integrazione personalizzata per sincronizzare il sistema di gestione della forza lavoro con Turni

Panoramica

Integrare Turni, l'app di gestione della pianificazione in Microsoft Teams, con il sistema di gestione della forza lavoro (WFM). Questa integrazione consente alla forza lavoro in prima linea di visualizzare e gestire le pianificazioni direttamente all'interno di Turni.

Questo articolo illustra come creare un connettore usando microsoft API Graph per facilitare questa integrazione.

È possibile configurare l'integrazione per una sincronizzazione dei dati unidirezionale o una sincronizzazione dati bidirezionale.

• Sincronizzazione unidirezionale (WFM sistema a turni): in questa configurazione, i dati di pianificazione nel sistema WFM vengono sincronizzati con Turni. Il connettore legge i dati nel sistema WFM e li scrive in Turni. Tuttavia, le modifiche apportate in Turni dagli utenti non vengono riflesse nuovamente nel sistema WFM.

• Sincronizzazione bidirezionale (WFM sistema e turni): questa configurazione consente una sincronizzazione bidirezionale. I dati di pianificazione nel sistema WFM vengono sincronizzati con Turni e tutte le modifiche apportate in Turni dagli utenti vengono sincronizzate con il sistema WFM. Il connettore convalida e approva le modifiche apportate dagli utenti in Turni in base alle regole di business applicate dal sistema WFM prima che le modifiche vengano scritte in Turni.

Terminologia usata in questo articolo

Prima di iniziare

Prerequisiti

• Determinare i dati da sincronizzare in base alle esigenze aziendali.
• Comprendere i concetti di autenticazione e autorizzazione nel Microsoft Identity Platform. Vedere Nozioni di base su autenticazione e autorizzazione.
• Amministrazione ruoli necessari:
  • Almeno un amministratore di applicazioni cloud per registrare un'app nel Interfaccia di amministrazione di Microsoft Entra
  • Amministratore globale per registrare l'integrazione della forza lavoro

Acquisire familiarità con il processo di integrazione

Ecco una panoramica dei passaggi di integrazione. Esaminare queste informazioni per comprendere il processo complessivo, incluso chi esegue ogni passaggio.

Passaggio 1: Creare il connettore

Per creare il connettore, completare la procedura seguente:

• Passaggio 1a: Sincronizzare le modifiche apportate in Turni al sistema WFM
• Passaggio 1b: Sincronizzare i dati dal sistema WFM ai turni

Passaggio 1a: Sincronizzare le modifiche apportate in Turni al sistema WFM

Per configurare il connettore per ricevere ed elaborare le richieste da Turni, è necessario implementare gli endpoint seguenti:

• /connect (obbligatorio)
• /update (obbligatorio)
• /read (facoltativo)

Determinare l'URL di base e gli URL dell'endpoint

L'URL di base (webhook) è {url}/v{apiVersion}, dove url e apiVersion sono le proprietà impostate nell'oggetto workforceIntegration quando si registra l'integrazione della forza lavoro.

I percorsi relativi degli URL dell'endpoint sono i seguenti:

• /connettersi: /connect
• /aggiornare: /teams/{teamid}/update
• /leggere: /teams/{teamid}/read

Ad esempio, se url è https://contosoconnector.com/wfi e apiVersion è 1:

• L'URL di base è https://contosoconnector/com/wfi/v1.
• L'endpoint /connect è https://contosoconnector/wfi/v1/connect.
• L'endpoint /update è https://contosoconnector/wfi/v1/teams/{teamid}/update.
• L'endpoint /read è https://contosoconnector/wfi/v1/teams/{teamid}/read.

Crittografia

Tutte le richieste vengono crittografate tramite AES-256-CBC-HMAC-SHA256. È possibile specificare la chiave privata condivisa quando si registra l'integrazione della forza lavoro. Le risposte inviate a Turni non devono essere crittografate.

Endpoint

POST /connect

Turni chiama questo endpoint per testare la connessione quando si registra l'integrazione della forza lavoro. Una risposta di esito positivo viene restituita solo se questo endpoint restituisce una risposta HTTP 200 OK .

Esempio

Richiesta
ConnectRequest

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

Risposta
Restituisce HTTP 200 OK

POST /teams/{teamid}/update

Turni chiama questo endpoint per ottenere l'approvazione quando viene apportata una modifica a un'entità Turni in una pianificazioneabilitata per l'integrazione della forza lavoro. Se questo endpoint approva la richiesta, la modifica viene salvata in Turni.

Poiché il sistema WFM è il sistema di registrazione, quando il connettore riceve una richiesta a questo endpoint, deve prima tentare di apportare la modifica nel sistema WFM. Se la modifica ha esito positivo, restituire l'esito positivo. In caso contrario, restituisce un errore.

Turni chiama questo endpoint per ogni modifica (incluse le modifiche avviate dal sistema del connettore/WFM). Se il connettore ha inviato un aggiornamento a Turni usando API Graph e ha aggiunto l'intestazioneX-MS-WFMPassthrough: workforceIntegratonId, la richiesta che arriva a questo endpoint avrà la stessa intestazione, che consente di identificare e gestire queste richieste in modo appropriato. Ad esempio, restituire l'esito positivo senza apportare la stessa modifica nel sistema WFM che sarebbe ridondante e può causare il blocco del connettore in un ciclo infinito.

Il diagramma seguente mostra il flusso di dati.

Restituire il codice di risposta
Qualsiasi risposta dall'integrazione, incluso un errore, deve avere un codice 200 OKdi risposta HTTP. Il corpo della risposta deve avere lo stato e il messaggio di errore che riflette lo stato di errore della sottochiamata appropriato. Qualsiasi risposta dall'integrazione diversa 200 OK da viene considerata come un errore e restituita al chiamante (client o Microsoft Graph).

Se si vuole configurare una sincronizzazione unidirezionale, impostare Turni di sola lettura

Per una sincronizzazione unidirezionale, è necessario rendere turni di sola lettura in modo che gli utenti non possano apportare modifiche in Turni. Per rendere turni di sola lettura, restituire una risposta di errore per tutte le richieste provenienti da Turni.

Ad esempio, per impedire agli utenti di apportare modifiche ai turni nella pianificazione, questo endpoint deve restituire una risposta di errore ogni volta che riceve una richiesta relativa a un'entità shift .

Esempio

Richiesta
WfiRequestContainer

Nell'esempio seguente viene illustrata una richiesta di Turni che chiede se un turno, il cui ID è SHFT_12345678-1234-1234-1234-1234567890ab e con le proprietà elencate nel corpo, può essere salvato in Turni. Questa richiesta è stata attivata quando un utente crea uno spostamento in Turni.

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

Risposta
WfiResponse

Operazione riuscita: restituisce HTTP 200 OK

Questo esempio mostra la risposta restituita se l'endpoint ha approvato la richiesta. In questo scenario, il turno viene salvato in Turni e l'utente può visualizzare lo spostamento nella pianificazione.

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

Errore: restituisce HTTP 200 OK

Questo esempio mostra la risposta restituita se l'endpoint ha negato la richiesta. In questo scenario, l'utente riceve un messaggio di errore "Impossibile aggiungere lo spostamento" in Turni.

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

Questo endpoint gestisce le richieste di Turni per recuperare i motivi di time off idonei o i turni idonei per le richieste di scambio per un utente.

Il diagramma seguente mostra il flusso di dati.

Restituire il codice di risposta
Qualsiasi risposta dall'integrazione, incluso un errore, deve avere un codice 200 OKdi risposta HTTP. Il corpo della risposta deve includere lo stato e il messaggio di errore che riflette lo stato di errore della sottochiamata appropriato. Qualsiasi risposta dall'integrazione diversa 200 OK da viene considerata come un errore e restituita al chiamante (client o Microsoft Graph).

Esempio: TimeOffReason

Richiesta

Nell'esempio seguente viene illustrata una richiesta di Turni che chiede per quali motivi di time off un utente (ID utente aa162a04-bec6-4b81-ba99-96caa7b2b24d) è idoneo. Questa richiesta è stata attivata quando l'utente richiede il time off in Turni.

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

Risposta
Operazione riuscita: restituisce HTTP 200 OK

La risposta seguente mostra che gli ID motivo di time off idonei per l'utente sono "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" e "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". In questo scenario, l'utente visualizza i motivi di time off corrispondenti tra cui scegliere in Turni.

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

Errore: restituisce HTTP 200 OK

In questo esempio viene restituita una risposta di errore perché il connettore non è riuscito a raggiungere il sistema WFM per recuperare i motivi di time off per l'utente.

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

Esempio: SwapRequest

Richiesta

L'esempio seguente mostra una richiesta di Turni che chiede quali turni sono idonei per uno scambio con il turno il cui ID è SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 tra il 2024-10-01T04:00:00.0000000Z e 2024-11-01T03:59:59.99900000Z.

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

Risposta
Operazione riuscita: restituisce HTTP 200 OK

La risposta seguente mostra che lo spostamento può essere scambiato con il turno il cui ID è 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, 
      } 
    }
  ]
}

Errore: restituisce HTTP 200 OK

In questo esempio viene restituita una risposta di errore perché il connettore non è riuscito a raggiungere il sistema WFM per recuperare i turni idonei per una richiesta di scambio per l'utente.

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

Passaggio 1b: Sincronizzare i dati dal sistema WFM ai turni

Usare le API Turni in Microsoft Graph per leggere i dati di pianificazione dal sistema WFM e scrivere i dati in Turni.

Ad esempio, per aggiungere un turno a Turni, usare l'API Crea turno .

Vedere le informazioni di riferimento su Microsoft API Graph v1.0 per le API Turni, elencate in Gestione turni.

Il diagramma seguente mostra il flusso di dati.

Sincronizzazione iniziale

Per la prima sincronizzazione, il connettore deve leggere i dati nel sistema WFM e scrivere i dati in Turni. È consigliabile sincronizzare due settimane di dati futuri.

Dopo la sincronizzazione iniziale

Dopo la prima sincronizzazione, è possibile scegliere di:

• Aggiornare i turni in modo sincrono con le modifiche apportate al sistema WFM: inviare un aggiornamento a Turni per ogni modifica apportata nel sistema WFM.

• Aggiornare in modo asincrono turni con modifiche nel sistema WFM: eseguire una sincronizzazione periodica scrivendo tutte le modifiche che si sono verificate nel sistema WFM entro un determinato intervallo di tempo (ad esempio, 10 minuti) in Turni.

  Tutte le operazioni di scrittura in Turni, incluse le operazioni di scrittura avviate dal connettore, attivano una chiamata all'endpoint /update del connettore. È consigliabile includere l'intestazione X-MS-WFMPassthrough: workforceIntegratonId in tutte le chiamate di scrittura in modo che il connettore possa identificarle e gestirle in modo appropriato. Ad esempio, se il sistema WFM ha avviato la modifica, approvarla senza applicare un aggiornamento al sistema WFM.

  Nota

  Se si sta configurando il connettore per una sincronizzazione bidirezionale dei dati tra il sistema WFM e Turni, escludere le modifiche avviate da Turni nella sincronizzazione periodica. Queste modifiche sono già scritte in Turni.

Passaggio 2: Registrare un'app nel Interfaccia di amministrazione di Microsoft Entra

Seguire questa procedura per registrare un'app per il connettore nel Microsoft Identity Platform, configurare le autorizzazioni per l'app per l'accesso a Microsoft Graph e ottenere un token di accesso.

1. Accedere al Interfaccia di amministrazione di Microsoft Entra almeno come amministratore di applicazioni cloud.

2. Registrare l'app. Per i passaggi, vedere Registrare un'applicazione con il Microsoft Identity Platform.

3. Assegnare le autorizzazioni dell'applicazioneSchedule.ReadWrite.All all'app per l'accesso solo app e ottenere un token di accesso.

   Per istruzioni dettagliate, vedere Ottenere l'accesso senza un utente.

   Il token di accesso verifica che l'app sia autorizzata a chiamare Microsoft Graph usando la propria identità usando l'autorizzazione Schedule.ReadWrite.All . Deve essere incluso nell'intestazione Authorization delle richieste.

Passaggio 3: Creare team e pianificazioni per la sincronizzazione

Configurare i team in Teams da sincronizzare. È possibile usare i team esistenti o creare nuovi team.

1. Configurare i team in Teams in modo che corrispondano ai team e alle posizioni nel sistema WFM. Assicurarsi di aggiungere le persone seguenti a ogni team:

   • Manager in prima linea come proprietari del team. Assicurarsi di aggiungere l'utente nell'intestazione MS-APP-ACTS-AS come proprietario del team di ogni rispettivo team.
   • Ruoli di lavoro in prima linea come membri del team.

2. Creare una pianificazione in Turni per ogni team. Per altre informazioni, vedere Creare o sostituire la pianificazione.

3. Aggiungere gruppi di pianificazione alla pianificazione in ogni team. I gruppi di pianificazione vengono usati per raggruppare i dipendenti in base alle caratteristiche comuni all'interno di un team. Ad esempio, i gruppi di pianificazione possono essere reparti o tipi di processo. Per altre informazioni, vedere pianificazioneTipo di risorsa gruppo.

4. Aggiungere dipendenti a ogni gruppo di pianificazione. Per altre informazioni, vedere Sostituire schedulingGroup.

Passaggio 4: Registrare e abilitare l'integrazione della forza lavoro

Un'integrazione della forza lavoro definisce le impostazioni di crittografia per la comunicazione tra turni e connettore, l'URL per i callback dai turni e i tipi di entità da sincronizzare.

Per registrare e abilitare l'integrazione della forza lavoro, seguire questa procedura:

• Passaggio 4a: Registrare l'integrazione della forza lavoro
• Passaggio 4b: Abilitare l'integrazione della forza lavoro per le pianificazioni del team

Passaggio 4a: Registrare l'integrazione della forza lavoro nel tenant

Per eseguire questo passaggio, è necessario essere un amministratore globale.

Usare l'API Create workforceIntegration per registrare l'integrazione della forza lavoro nel tenant.

Ecco un esempio di richiesta.

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

Per informazioni dettagliate, vedere la tabella seguente. Per altre informazioni, vedere workforceIntegration resource type (Tipo di risorsa di integrazione).

Passaggio 4b: Abilitare l'integrazione della forza lavoro per le pianificazioni del team

Abilitare l'integrazione della forza lavoro nelle pianificazioni da gestire. A tale scopo, usare l'API Crea o sostituisci pianificazione per creare o aggiornare la pianificazione per i team.

Ecco un esempio di richiesta.

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

• Specificare il workforceIntegrationId generato quando è stata registrata l'integrazione della forza lavoro.
• È possibile abilitare un massimo di un'integrazione della forza lavoro in base a una pianificazione. Se si includono più elementi workforceIntegrationId nella richiesta, viene usato il primo.

Risoluzione dei problemi

Connettore

Quando il connettore risponde a una richiesta di Turni, cosa accade se restituisce un codice di risposta diverso da 200? Fa la differenza se restituisce uno stato diverso da 200 nel corpo della risposta?

Esiste una differenza tra questi due scenari.

• Se il connettore restituisce un codice di risposta diverso da 200, Turni tenta di ripetere più volte gli endpoint /read e /update. Alla fine, Turni visualizza un messaggio "Qualcosa è andato storto. La configurazione dell'integrazione della forza lavoro nel team ha risposto con dati non validi." messaggio di errore.
• Se il connettore restituisce uno stato diverso da 200 nel corpo della risposta, Turni visualizza un messaggio "Qualcosa è andato storto. Non è stato possibile completare la modifica", messaggio di errore e smette di ritentare gli endpoint.

Cosa accade se il connettore restituisce dati non validi nel corpo della risposta?

Turni tenta di ripetere più volte gli endpoint /read e /update. Alla fine, Turni visualizza un messaggio "Qualcosa è andato storto. L'integrazione della forza lavoro configurata nel team ha risposto con dati non validi." messaggio di errore.

Ricerca per categorie identificare se la richiesta è stata originariamente effettuata in Turni o nel sistema WFM per evitare un ciclo infinito?

Aggiungere l'intestazione X-MS-WFMPassthrough: workforceIntegratonId a tutte le chiamate di scrittura e aggiornamento per identificare/ignorare le modifiche attivate dal connettore. Questa intestazione viene usata per indicare che la richiesta viene eseguita a causa di una chiamata precedente effettuata dal connettore per API Graph per sincronizzare i dati dal sistema WFM a Turni.

Registrazione dell'integrazione della forza lavoro

Ho registrato l'integrazione della forza lavoro e ho specificato "eligibilityFilteringEnabledEntities" tra cui "SwapRequest, OfferShiftRequest e TimeOffReason", ma il corpo della risposta non mostra l'elenco "eligibilityFilteringEnabledEntities".

Il filtro di idoneità è attualmente supportato tramite l'endpoint https://graph.microsoft.com/beta , non l'endpoint https://graph.microsoft.com/v1 .

Ho registrato l'integrazione della forza lavoro e aggiunto "supportedEntities", ma ho ricevuto una risposta di 400 richieste non valide e un "payload non valido: valore richiesto 'shift, ....' non è stato trovato." messaggio

Assicurarsi che ogni entità Turni nel corpo della supportedEntities richiesta elenco inizi con una lettera maiuscola. Ad esempio, "supportedEntities":"Shift,SwapRequest,OpenShift".

È stata registrata l'integrazione della forza lavoro e sono stati implementati gli endpoint /connect, /update e /read, ma il webhook non funziona.

Assicurarsi che l'integrazione della forza lavoro sia abilitata per la pianificazione del team. Verificare inoltre che le proprietà url e apiVersion siano corrette.

Riferimento all'endpoint

Richiesta

ConnectRequest

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

WfiRequestContainer

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

Numero di elementi in una richiesta:

• Nella maggior parte dei casi, una richiesta ha un elemento.
• Alcune richieste, ad esempio le approvazioni delle richieste di cambio di turno, hanno cinque elementi: una richiesta di scambio PUT, due turni DELETE (turni esistenti) e due turni POST (nuovi turni).

WfiRequest

Per POST /teams/{teamId}/update

Per POST /teams/{teamsId}/read

WfiRequestHeader

X-MS-WFMPassthrough: workforceIntegratonId non verrà incluso in WfiRequestHeader. Deve essere estratto da HttpRequest.

Risposta

WfiResponseContainer

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

WfiResponse

WfiResponseBody

WfiResponseError

Articoli correlati

• Turni per l'organizzazione in prima linea
• Connettori turni