Sincronizzare il calendario di Office 365 con il tuo applicativo: l'esempio di Nosco

Il calendario di Office 365 è un sistema di calendari online che funziona in sinergia con gli altri strumenti della suite di Microsoft. Offre due vantaggi principali: consente di tenere monitorate le attività giornaliere e di lavorare con le altre applicazioni di Office 365, come Word e Excel.

Per ottenere questi vantaggi, è fondamentale che il calendario sia sincronizzato con i sistemi gestionali in uso dal team aziendale. 

Se nell’articolo precedente abbiamo illustrato le linee generali per l’integrazione dei sistemi, in questa sede prendiamo quindi in esame un caso concreto e spieghiamo come abbiamo sincronizzato le attività di Nosco con gli eventi del calendario di Office 365.

Obiettivi della sincronizzazione

La sincronizzazione ha due principali obiettivi:

• Quando un’attività viene assegnata a un utente in Nosco deve essere creato in automatico un evento relativo nel calendario dell’utente assegnatario, con le stesse indicazioni di giorno e durata. Nel caso all’assegnatario venga rimossa l’attività da Nosco, deve essere rimosso anche l’evento dal calendario. Nel caso un’attività subisca modifiche in termini di giorno, durata o assegnatario in Nosco, deve essere aggiornato in automatico anche l’evento nel calendario.
• Allo stesso modo, nel caso un evento nel calendario subisca modifiche in termini di giorno e durata, deve essere aggiornata in automatico anche l’attività in Nosco.

Soluzioni per la sincronizzazione

Per quanto riguarda il primo punto, Office 365 possiede una serie di API per la gestione degli eventi a calendario (le trovi qui) grazie alle quali possiamo ottenere una lista di tutti i nostri eventi, crearli, cancellarli o modificarli.

Per poter interagire con queste API, dobbiamo possedere un token di autenticazione rilasciato da Office 365 che identifichi l’utente di cui vogliamo accedere alle risorse e che sia dotato dei permessi richiesti per le azioni che vogliamo compiere. 

In Nosco otteniamo questo token grazie al meccanismo di login, che sfrutta il SSO di Office 365 (di cui ho parlato anche qui).

Fatto questo possiamo avviare la nostra comunicazione con Office 365. In questa pagina possiamo trovare l’elenco di tutte le API disponibili per gestire i nostri eventi a calendario e tutti gli attributi che possiamo assegnare ad un evento (durata, giorno, ora, luogo, etc.).

Di seguito un esempio del body di una chiamata per creare un nuovo evento a calendario (endpoint  https://graph.microsoft.com/v1.0/me/calendar/events) che avrà come titolo “Riunione Interna” e una durata di 2 ore il 2021-07-29.:

---

subject: "Riunione Interna",

  start: {

    dateTime: '2021-07-29T14:00:00Z', 

    timeZone: 'UTC'

    },

  end: {

    dateTime: '2021-07-29T16:00:00Z',

    timeZone: 'UTC'

 }

---

In risposta riceveremo da Office 365 l’oggetto appena creato ed in particolar modo il suo identificativo, che sarà necessario per accedere a questa specifica risorsa ad esempio per aggiornarla o cancellarla (utilizzando le opportune API).

Per raggiungere il secondo obiettivo dobbiamo invece affidarci alle subscriptions di Office 365: vediamo come ottenerne una.

Anche per la gestione delle subscriptions esistono delle API che permettono di richiedere, rinnovare (in quanto hanno una scadenza di alcuni giorni) oppure cancellarle.

Quali sono le informazioni di cui Office 365 ha bisogno per richiedere una subscription?

1. Il token identificativo dell’utente
2. Il tipo di risorsa di cui siamo interessati a rimanere aggiornati
3. Gli eventi a cui siamo interessati (creazione, modifica, cancellazione, ...)
4. La scadenza (dopo tale data Office 365 smetterà di inviarci le notifiche relative)
5. Un indirizzo url che sarà chiamato da Office 365 per notificarci un determinato evento.

Ecco un esempio di codice per richiedere di essere notificati sugli aggiornamenti degli eventi del calendario di uno specifico utente:

---

'changeType': 'updated',

'notificationUrl': url_per_gestire_evento,

'resource': 'me/calendar/events',

'expirationDateTime': Time.now + 2.days,

'latestSupportedTlsVersion': ‘v1_2’

---

Analogamente possiamo decidere di eliminare/refreshare la subscription (utilizzando una chiamata delete/patch).

Una volta eseguita la richiesta, Office 365 farà immediatamente una chiamata di prova all’url indicato, per assicurarsi che sia un url valido e che sia sotto il nostro controllo. 

Per superare questo check di sicurezza basterà rispondere con un token che è contenuto nella richiesta. Da questo momento in poi (e per i prossimi 2 giorni) ogni modifica fatta nel calendario dell’utente selezionato ci sarà notificata all’url specificato tramite una richiesta post che conterrà tutti i campi dell’evento a calendario di Office 365.

Conclusione

Abbiamo visto come integrare il calendario 365 sia abbastanza semplice, la parte più complessa è in realtà accoppiare gli eventi del calendario con la logica di business della propria applicazione. In modo da rendere chiaro per l'utente come un'azione sul calendario influisca sul nostro software e viceversa.