> For the complete documentation index, see [llms.txt](https://manuale.opencontent.it/manuali/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manuale.opencontent.it/manuali/manuale-operativo-interno/configurazione-di-openagenda/sincronizzazione-eventi-cms.md).

# 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:

{% stepper %}
{% step %}

## Installa il modulo event\_link nel CMS

L'installazione crea la classe di contenuto `event_link` e l'utente tecnico `openagendabot`.
{% endstep %}

{% step %}

## Esegui lo script di setup

Lancia `set_event_link_webhooks.php`: registra i due webhook sull'agenda e genera il token JWT.
{% endstep %}

{% step %}

## 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.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Per i dettagli operativi di installazione, fai riferimento alle istruzioni tecniche di setup del modulo.
{% endhint %}

## 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.

{% hint style="info" %}
Segna in calendario un rinnovo circa 350 giorni dopo ogni rigenerazione del token, per non farti cogliere di sorpresa alla scadenza.
{% endhint %}

### 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

{% stepper %}
{% step %}

## 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.
{% endstep %}

{% step %}

## Rigenera il token

Il metodo dipende dal tipo di autenticazione usata nel webhook.

{% tabs %}
{% tab title="Authorization: Bearer" %}
Accedi con l'account `openagendabot` e rigenera il token Bearer dal profilo utente. Copialo subito: ti serve nel passo successivo.
{% endtab %}

{% tab title="Authorization: Basic" %}
Apri il terminale e lancia il comando:

```bash
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>
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

## 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.

{% hint style="warning" %}
Aggiorna entrambi i webhook, non solo il Publish.
{% endhint %}
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}
{% endstepper %}