Sincronizzazione eventi con il CMS

OpenAgenda e il sito CMS (OpenCity) sono due applicativi separati che si sincronizzano tramite webhook: quando un evento viene pubblicato o eliminato su OpenAgenda, viene inviata automaticamente una notifica al CMS, che crea, aggiorna o rimuove il corrispondente contenuto di tipo event_link (Evento OpenAgenda).

Come funziona

Sul lato OpenAgenda sono configurati due webhook:

• uno per la pubblicazione degli eventi: crea o aggiorna un event_link nel CMS tramite API REST;

• uno per l'eliminazione degli eventi: rimuove il nodo corrispondente nel CMS.

Le chiamate vengono autenticate tramite un token JWT intestato all'utente tecnico openagendabot. Il token è firmato con chiave RSA privata (jwt/private.key.pem) e ha durata di 1 anno.

L'utente openagendabot viene creato automaticamente nel CMS dall'installer del modulo event_link.

La consegna dei webhook è gestita da un worker supervisor in esecuzione sul server cron, che garantisce la coda e il retry in caso di errori transitori.

Rinnovo del token JWT

Alla scadenza annuale del token sono disponibili due opzioni:

• rieseguire lo script di setup set_event_link_webhooks.php, che rigenera il token JWT;

• generare una nuova password per l'utente openagendabot nel CMS, ottenere un bearer token e inserirlo nella configurazione del webhook. Anche questo token ha validità 1 anno.

Configurazione iniziale

Per collegare una nuova coppia agenda/CMS:

1

Installa il modulo event_link nel CMS

L'installazione crea la classe di contenuto event_link e l'utente tecnico openagendabot.

2

Esegui lo script di setup

Lancia set_event_link_webhooks.php: registra i due webhook sull'agenda e genera il token JWT.

3

Aggiungi il worker supervisor

Sul server cron, aggiungi il worker supervisor per la nuova istanza agenda. Il worker gestisce la coda di consegna dei webhook.

Per i dettagli operativi di installazione, fai riferimento alle istruzioni tecniche di setup del modulo.

La sincronizzazione smette di funzionare

Se gli eventi pubblicati su OpenAgenda non appaiono (o non vengono rimossi) dal sito, la causa più comune è la scadenza del token dell'utente openagendabot. Il token ha durata 365 giorni dalla sua generazione.

Segna in calendario un rinnovo circa 350 giorni dopo ogni rigenerazione del token, per non farti cogliere di sorpresa alla scadenza.

Conferma la diagnosi

I webhook si trovano al path /webhook/list del tenant OpenAgenda, ad esempio https://agenda.comune.DOMINIO/webhook/list. Trovi due webhook attivi:

• Publish event link — pubblica gli eventi sul sito (metodo POST);

• Delete event link — rimuove gli eventi dal sito (metodo DELETE).

Clicca Logs accanto al webhook Publish event link. Se vedi righe rosse con codice 401, il token è scaduto: procedi con la risoluzione qui sotto. Se il codice è diverso da 401, apri l'ultimo log fallito e leggi il campo Response in fondo per capire la causa specifica.

Risoluzione

1

Recupera le credenziali dell'utente openagendabot

Vai su Amministra → Gestione accessi redazione e cerca l'utente openagendabot. Verifica la mail di recupero associata. Se non hai accesso alla mailbox, modifica temporaneamente la mail con la tua, esegui il recupero password, poi rimetti la mail originale.

2

Rigenera il token

Il metodo dipende dal tipo di autenticazione usata nel webhook.

Authorization: Bearer

Accedi con l'account openagendabot e rigenera il token Bearer dal profilo utente. Copialo subito: ti serve nel passo successivo.

Authorization: Basic

Apri il terminale e lancia il comando:

echo -n "nomeutente:password" | base64

La stringa restituita va inserita dopo Authorization: Basic nella configurazione del webhook. Esempio di header completo:

Host: www.comune.udine.it
X-Target-Node: 90
Authorization: Basic <token>

3

Aggiorna entrambi i webhook

Torna su /webhook/list e clicca Edit su entrambi i webhook (Publish e Delete). Sostituisci il valore nel campo Authorization con il nuovo token.

Aggiorna entrambi i webhook, non solo il Publish.

4

Esegui il Test

Clicca Test su entrambi i webhook. Una risposta verde (codice 2xx) conferma che il problema è risolto. Se il test fallisce ancora, verifica di aver copiato il token completo, senza spazi o interruzioni di riga.

5

Fai Retry sulle esecuzioni fallite

Vai nei Logs del webhook Publish e clicca Retry su tutte le righe rosse, partendo dalla più vecchia. Gli eventi persi durante il periodo di malfunzionamento vengono così risincronizzati sul sito.