Guida per sviluppatori: aggiungere un nuovo applicativo
Questa sezione descrive il processo completo per rendere disponibile un nuovo tipo di applicativo nel Tenant Manager, dalla definizione dello schema di configurazione alla scrittura del workflow Windmill.
Panoramica del processo
1. Aggiungi l'applicativo al catalogo (collezione `apps`)
│
â–¼
2. Definisci lo schema Form.io (collezione `config_schemas`)
│
â–¼
3. Configura le transizioni di stato (collezione `windmill_scripts`)
│
â–¼
4. Scrivi i workflow Windmill (repo `windmill platform`)
│
â–¼
5. Testa su QA, poi promuovi in produzionePasso 1 — Aggiungere l'applicativo al catalogo
Accedi al backoffice PocketBase e aggiungi una nuova riga nella collezione apps:
name
Identificativo tecnico (slug)
integrazione-atti-sicraweb
description
Nome leggibile mostrato nella UI
Integrazione Atti Sicraweb
icon
Icona (nome icona Bootstrap Icons)
file-earmark-text
[SCREENSHOT: Backoffice PocketBase — form di creazione nuova riga in collezioneapps]
Il valore di name diventa l'app_name di tutti i tenant di quel tipo e deve essere stabile: cambiarlo dopo che esistono tenant attivi rompe i riferimenti.
Passo 2 — Definire lo schema Form.io
Lo schema Form.io determina quali campi di configurazione il team delivery vedrà quando crea o modifica un tenant di questo tipo.
Aggiungi una riga nella collezione config_schemas:
app_name
Deve corrispondere esattamente al name dell'app appena creata
version
Versione dello schema (es. 1)
schema
Definizione JSON dello schema Form.io
Come costruire lo schema:
Il backoffice del Tenant Manager include un editor Form.io drag-and-drop per costruire lo schema visivamente senza scrivere JSON a mano.
[SCREENSHOT: Editor Form.io nel backoffice — interfaccia drag-and-drop per aggiungere campi]
Linee guida per la definizione dei campi:
Usa
keystabili e in snake_case (es.endpoint_url,api_key) — i workflow Windmill li usano come riferimentoMarca come
requiredsolo i campi realmente obbligatori per il funzionamento dell'applicativoRaggruppa i campi correlati in pannelli Form.io per migliorare la leggibilità per il team delivery
Per le credenziali sensibili, usa il tipo campo
passwordper mascherarne la visualizzazioneTesta lo schema compilando il form nella UI del Tenant Manager prima di renderlo disponibile al team delivery
Versionamento dello schema:
Se in futuro lo schema deve cambiare in modo incompatibile con le configurazioni esistenti, crea una nuova riga con version incrementata invece di sovrascrivere quella corrente. I tenant esistenti mantengono il riferimento alla versione con cui sono stati creati.
Passo 3 — Configurare le transizioni di stato
Per ogni transizione di stato che deve avviare un workflow Windmill, aggiungi una riga nella collezione windmill_scripts:
app_name
Tipo di applicativo
integrazione-atti-sicraweb
from_status
Stato di partenza
activation_pending
to_status
Stato target
active
windmill_path
Path del workflow nel workspace platform
f/tenant_manager/integrazione_atti_sicraweb_provision
kind
Tipo di operazione
provision / deploy / archive / delete
[SCREENSHOT: Backoffice PocketBase — collezionewindmill_scriptscon le righe di un applicativo esistente come riferimento]
Non tutte le transizioni devono necessariamente avere un workflow associato. Se per una certa transizione non è richiesta alcuna automazione infrastrutturale, lascia la transizione senza riga corrispondente: il Tenant Manager avanzerà lo stato direttamente.
Passo 4 — Scrivere i workflow Windmill
I workflow vanno aggiunti nel repository opencity-labs/integrations/windmill, nel workspace platform.
Convenzione di naming:
Esempi:
Parametri in ingresso:
Il Tenant Manager passa automaticamente al workflow i seguenti parametri:
I campi in config corrispondono esattamente alle key definite nello schema Form.io.
Struttura consigliata di un workflow:
Subflow condiviso per la callback:
Non reimplementare la logica di callback. Alla fine del workflow, chiama:
passandogli callback_url e lo stato target. Questo subflow si occupa di:
Chiamare il Tenant Manager via API
Avanzare il tenant allo stato target
Liberare lo stato transitorio
Workflow multi-tenant (pattern orchestratore):
Per i workflow che devono operare su tutti i tenant attivi di un tipo (es. sincronizzazione periodica), usa il pattern orchestratore:
Questo elimina la necessità di hardcodare la lista dei tenant nel workflow.
Passo 5 — Test e promozione in produzione
Fai merge del workflow nel branch
developdel repowindmill platform→ viene deployato automaticamente su Windmill QACrea un tenant di test nel TM QA con il nuovo applicativo
Percorri l'intero ciclo di vita: crea → attiva → configura → metti in produzione → archivia
Verifica che ogni transizione completi correttamente e che il tenant avanzi allo stato atteso
Verifica i log del job Windmill per ogni transizione
Se tutti i test passano, fai merge su
main→ promozione a Windmill Produzione
Prima di rendere disponibile il nuovo applicativo al team delivery, assicurati che:
Lo schema Form.io sia completo e validato
Tutte le transizioni previste abbiano il workflow corrispondente o siano esplicitamente documentate come manuali
Il team delivery abbia una scheda nella sezione Applicativi supportati aggiornata con i campi di configurazione richiesti
Last updated
Was this helpful?