Come funziona l'automazione con Windmill

Ogni transizione di stato di un tenant (es. da In attesa ad Attivato, da Attivato a In produzione) può avviare automaticamente un workflow su Windmill, il motore di automazione della piattaforma. È Windmill che esegue le operazioni infrastrutturali concrete: creare database, deployare stack, configurare risorse cloud, ecc.

Il team delivery non interagisce direttamente con Windmill durante le operazioni ordinarie, il Tenant Manager fa da intermediario. Questa sezione spiega cosa succede "sotto il cofano" per permettere di interpretare correttamente lo stato del sistema e agire in caso di anomalie.

---

Il flusso completo

Team delivery clicca "Attiva" nel Tenant Manager
        │
        ▼
Tenant Manager imposta stato transitorio (es. "Provisioning")
e blocca ulteriori azioni sul tenant
        │
        ▼
Tenant Manager chiama il workflow Windmill configurato
per quella transizione + quel tipo di applicativo,
passandogli tutti i dati del tenant
        │
        ▼
Windmill esegue il workflow
(crea DB, S3, deploys stack, ecc.)
        │
        ├─── Successo ──────────────────────────┐
        │                                       ▼
        │                         Windmill chiama la callback URL
        │                         → TM avanza il tenant allo stato target
        │                           (es. "Attivato")
        │
        └─── Errore ─────────────────────────┐
                                             ▼
                               Tenant rimane bloccato
                               nello stato transitorio
                               → intervento manuale necessario

TODO: [SCREENSHOT: Log di un job Windmill visibile dalla scheda del tenant — link diretto al job in esecuzione]

---

Cosa viene passato al workflow

Quando il Tenant Manager avvia un workflow Windmill, gli trasmette automaticamente:

• Tutti i campi della configurazione del tenant (compilati tramite Form.io)

• Il cliente, il tipo di applicativo, l'UID, lo slug

• Il cluster di destinazione

• Lo stato corrente e lo stato target

• Una URL di callback pre-autenticata e monouso

La callback URL è il meccanismo con cui il workflow, a operazione completata, comunica al Tenant Manager di avanzare lo stato. Ogni workflow deve chiamarla alla fine, sia in caso di successo che di fallimento gestito.

Per gli sviluppatori: esiste un subflow Windmill condiviso che gestisce la chiamata di callback verso PocketBase. Tutti i workflow custom devono richiamarlo in coda invece di reimplementare la logica. Vedi la sezione Guida per sviluppatori.

---

Il workspace Windmill della piattaforma

I workflow relativi al Tenant Manager risiedono nel workspace platform di Windmill — distinto dal workspace integrations usato per le integrazioni applicative.

Il repository sorgente è opencity-labs/core-services/windmill-platform . Le modifiche seguono il flusso standard: sviluppo su QA → promozione a Produzione tramite CI/CD GitLab.

---

Windmill come orchestratore delle integrazioni

Oltre ai workflow di provisioning e deploy, Windmill può essere usato come orchestratore per le esecuzioni periodiche delle integrazioni.

Il pattern previsto è:

1. Un flow Windmill interroga il Tenant Manager via API per ottenere la lista di tutti i tenant attivi di un determinato tipo (es. tutti i tenant Integrazione Atti Sicraweb in stato In produzione)

2. Per ciascuno, avvia il flow di integrazione passandogli la configurazione del tenant

3. Questo elimina la necessità di mantenere liste di tenant hardcoded nei singoli workflow

Questo approccio è lo standard a cui tendere per i nuovi applicativi. I workflow esistenti che usano ancora configurazioni hardcoded sono candidati alla migrazione.

---

Cosa fare se un tenant è bloccato

Se un workflow Windmill va in errore prima di chiamare la callback, il tenant rimane bloccato nello stato transitorio (es. Provisioning, Deploying) a tempo indeterminato.

Come intervenire:

1. Apri la scheda del tenant nel Tenant Manager

2. Verifica il log del job Windmill (il link al job è visibile nella scheda, se disponibile) per capire la causa dell'errore

3. Se il problema è risolto o il workflow deve essere rieseguito manualmente, usa il pulsante "Sblocca" nella scheda del tenant per riportarlo allo stato precedente

4. Una volta sbloccato, è possibile ritentare la transizione

Per errori ricorrenti o non diagnosticabili dalla scheda del tenant, contatta il team sviluppo fornendo l'UID del tenant e il timestamp dell'operazione.