Moduli custom
Estendi il CRM senza scrivere codice: crea nuovi moduli e campi a runtime, organizza il form, gestisci le picklist e importa/esporta i dati.
La creazione e la modifica dei moduli custom sono operazioni da amministratore. Una volta creato il modulo, i record al suo interno seguono i normali permessi RBAC (per modulo, per azione e per campo) come qualsiasi modulo core.
01Cosa sono i moduli custom
Oltre ai sei moduli di serie (Account, Contatti, Lead, Trattative, Attività, Note), puoi definire nuovi moduli con campi arbitrari senza scrivere codice e senza rilasci: tutto avviene a runtime dal pannello di amministrazione. Un modulo custom è a tutti gli effetti un modulo di prima classe: eredita CRUD, import/export, storico modifiche, note, allegati, aggiornamento massivo, filtri avanzati e permessi.
- Modulo: il contenitore (es.
contratti,ticket,immobili). - Campo: un attributo del record, con un tipo di dato preciso.
- Gruppo: una sezione del form che raccoglie più campi correlati.
02Creare un modulo
Vai in Impostazioni → Moduli personalizzati → Nuovo modulo.
Ti serviranno:
- Chiave del modulo (
moduleKey): l'identificativo tecnico, es.contratti. Diventa parte dell'URL API (/api/records/contratti) ed è di fatto permanente: sceglila con cura, minuscola e senza spazi. - Etichette: nome singolare e plurale (es. "Contratto" / "Contratti") usati in tutta la UI, più un'icona.
- Stato: un modulo può essere attivato o disattivato senza essere eliminato.
Il wizard di creazione è un builder in bozza: prepari nome, icona, sezioni e campi tutti insieme e li sottometti in un colpo solo. Per le modifiche successive si usa l'editor del modulo (click sul modulo dalla lista), dove le azioni reversibili (aggiungere/nascondere campi, rinominare sezioni, spostare, cambiare il titolo) offrono un «Annulla» immediato nel toast.
03Aggiungere campi e sceglierne il tipo
Ogni campo ha una chiave (immutabile: è la chiave sotto cui il valore viene salvato, rinominarla orfanerebbe i dati), un'etichetta (modificabile a piacere) e un tipo di dato. I tipi disponibili:
| Tipo | A cosa serve |
|---|---|
text | Testo su una riga. |
textarea | Testo lungo su più righe. |
number | Valore numerico. |
date | Data (senza ora). |
datetime | Data e ora. |
checkbox | Booleano sì/no. |
picklist | Elenco di opzioni gestito e riusabile: vedi sotto. |
select | Elenco a opzioni statiche. Mantenuto per i campi legacy; per i nuovi campi usa picklist. |
lookup | Relazione verso un altro modulo, core o custom, anche il modulo stesso (es. ticket padre/figlio). Il campo punta a un record esistente, con picker di ricerca. |
autonumber | Progressivo automatico (es. TICKET-001): prefisso, zeri di riempimento e valore di partenza a scelta. Lo assegna il sistema alla creazione. |
I campi si riordinano con il drag-and-drop. Un campo può essere reso obbligatorio; se lo rendi obbligatorio quando esistono già dei record, ti verrà chiesto un valore di default con cui il sistema compila i record esistenti. Altre due proprietà utili per campo:
- Titolo del record: il campo marcato come titolo (azione «Imposta come titolo», uno per modulo) dà il nome al record in breadcrumb e schede.
- Chiave di dedup: i campi marcati «usa per rilevamento duplicati» alimentano la ricerca duplicati.
Nota sull'autonumber: ne è ammesso uno per modulo,
e il contatore si può reimpostare solo finché il modulo non contiene record.
Organizzare i campi in gruppi
I campi si raccolgono in gruppi, che diventano sezioni distinte nella vista del record: es. "Dati anagrafici", "Condizioni economiche", "Note interne". Un gruppo è puramente organizzativo: eliminarlo non cancella i suoi campi, che tornano semplicemente non raggruppati.
04Picklist e select a confronto
Entrambi i tipi mostrano un elenco di scelte, ma sono profondamente diversi nella gestione:
- Picklist (consigliato): le opzioni vivono in un elenco centralizzato e riusabile: le gestisci (aggiungi, rinomina, disattiva, riordina) dal gestore Picklist, con eventuali colori. Lo stesso elenco può essere condiviso e i valori restano coerenti tra i record. Quando crei un campo picklist puoi indicare qualche opzione iniziale, che serve solo da seme: da lì in poi si gestiscono dal gestore Picklist.
- Select (legacy): le opzioni sono una lista statica scritta direttamente sul campo. Continua a funzionare per i campi creati in passato, ma non è più la scelta suggerita per i nuovi campi.
Per la gestione dettagliata delle liste di valori vedi anche l'API Picklist: la stessa lista è amministrabile via UI o via API.
05Modificare la struttura in sicurezza
La struttura di un modulo si può cambiare anche dopo che contiene dati, ma alcune operazioni toccano i dati esistenti. Le regole:
- Cambio del tipo di un campo: il sistema converte i dati esistenti. Se non tutti i valori sono convertibili al nuovo tipo (es. testo → numero con valori non numerici), l'operazione viene bloccata e ti vengono mostrate le righe problematiche. Gli allargamenti sicuri (testo ↔ testo lungo, select ↔ picklist) sono sempre ammessi.
- Eliminazione di un campo: di default è una disattivazione "morbida": i dati restano e vengono ripristinati se ri-aggiungi lo stesso campo. Esiste anche un'eliminazione definitiva (purge) che rimuove il campo e cancella i suoi valori da tutti i record.
Il cambio di tipo di un campo converte i dati e l'eliminazione definitiva di un campo li rimuove: sono operazioni che non si annullano dall'interfaccia. Fai un export del modulo prima di intervenire su un campo che contiene dati importanti.
L'eliminazione di un intero modulo è una cancellazione definitiva, protetta da una conferma esplicita (devi digitare la chiave del modulo). Rimuove tutti i suoi record e "orfanizza" gli oggetti collegati: workflow, picklist, note e allegati che vi facevano riferimento. Esporta i dati prima.
06Personalizzare le tab del dettaglio record
La scheda di ogni record è organizzata in tab (Dettagli, Aggiornamenti,
Documenti, Note, Email, Correlati…). Quali tab compaiono lo decide l'amministratore,
modulo per modulo (e vale per tutti i moduli, core e custom) da
Impostazioni → Funzionalità moduli:
- Tab attivabili/disattivabili: ogni tab tranne Dettagli si può spegnere per i moduli dove non serve (es. niente Documenti su un modulo di soli codici). Di default sono tutte attive; Note è l'unica opt-in.
- Vincoli tecnici rispettati: alcune tab hanno senso solo dove esistono i dati: Fatturazione su account/contatti, Prodotti e servizi sulle trattative, Email sui moduli agganciati dalla posta in arrivo (account, contatti, lead). Lì dove non sono possibili, l'interruttore è disabilitato con la spiegazione.
- Relazioni promosse a tab: di norma i record collegati vivono tutti dentro Correlati; per i moduli "densi" puoi promuovere una singola relazione a tab dedicata (es. la tab «Interventi» sulla scheda di un ticket). Si sceglie relazione per relazione, dallo stesso pannello.
È il modo per dare a ogni modulo custom una scheda su misura: prima disegni i campi e i gruppi nell'editor, poi scegli le tab e le relazioni da mettere in evidenza. Chi usa il record vede solo ciò che è rilevante.
07Usare i record: UI, import/export e API
Una volta definito il modulo, i suoi record si comportano come quelli dei moduli core: lista con filtri avanzati e ordinamento, dettaglio con storico modifiche, note e allegati, aggiornamento massivo e permessi per campo.
- Import / export: come per i moduli core, export in CSV e XLSX e import da CSV: l'export rispetta i filtri e i permessi di campo; l'import ha una fase di anteprima (validazione riga per riga, mapping delle colonne) e una di esecuzione.
- API: i record custom passano dal motore generico:
/api/records/<moduleKey>. Stessa envelope, stessa paginazione e stessi filtri delle risorse core.
curl "https://crm.tuodominio.it/api/records/contratti?limit=20" \ -H "Authorization: Bearer <accessToken>"
- Per definire e ispezionare la struttura (moduli, campi, gruppi) via API vedi API · Moduli custom.
- Per leggere e scrivere i record via il motore generico vedi API · Record generici.
- Una volta che il modulo esiste, puoi automatizzarlo con i workflow (trigger su creazione/modifica dei suoi record).