Modello di dati completo: entità JSON, relazioni e ontologia

Questa pagina descrive il modello di dati completo di un account Omniscol: le entità, i loro campi principali e le loro relazioni. Estende la pagina concettuale Organizzazione dei dati, che spiega il perché (repertorio della scuola ↔ orario, copie locali); qui l'obiettivo è il cosa — una mappa strutturale utilizzabile, in particolare per mettere in relazione il modello con un repertorio esterno (gestionale, directory, sistema informativo).

Pagina tecnica. Questo riferimento si rivolge all'integrazione e all'appaiamento con un sistema esterno. Non è necessario all'uso corrente di Omniscol: per comprendere l'organizzazione dei dati sul piano operativo, si veda Organizzazione dei dati.

Tutti i dati di un istituto sono organizzati sotto forma di albero. Le entità descritte di seguito (utenti, anni scolastici, orari, assenze, eventi, ecc.) corrispondono ai diversi rami di questa struttura. Il riferimento normativo è lo schema JSON dell'account. Può essere consultato in due forme:

• la sorgente grezza (lo schema JSON così com'è), servita dall'account all'indirizzo https://api.omniscol.com/api/guest/school_schema.json;
• il visualizzatore ad albero, leggibile su omniscol.com/it/datamodel (e il riferimento API corrispondente su omniscol.com/it/developers).

Questo schema descrive esattamente l'archiviazione fisica nel database, sotto forma di documento JSON. Questa pagina ne fornisce una lettura organizzata e stabile nel tempo.

Il documento scuola: la radice

Il documento radice riunisce il repertorio durevole dell'istituto e tutte le sue pianificazioni. I suoi sottoalberi di primo livello:

I sottoalberi indicati come «dizionario» sono oggetti JSON le cui chiavi sono identificativi stabili (il perno di qualsiasi messa in relazione esterna — si veda la sezione finale).

Campi trasversali: _extids e wishes

Due campi ricorrono su molte entità. Per non ripeterli in ogni schema, sono descritti qui una sola volta.

• _extids (ExternalIds) — tabella degli identificativi dell'entità nei sistemi esterni, ad esempio { "auriga": "12345" }. Presente sulle entità sincronizzabili (materie, famiglie, utenti, siti, aule, risorse, professori, classi, gruppi…). È il punto di ancoraggio di un appaiamento con un repertorio esterno (si veda la sezione finale).
• wishes — vincoli orari: disponibilità, fasce orarie preferite o da evitare, volume orario massimo, aula preferita… Presente sulla maggior parte delle entità pianificabili: utenti, professori e materie di un orario, gruppi, classi, aule, fasce orarie di sito, griglie di sorveglianza. A seconda del perimetro, questi vincoli sono globali (livello scuola) o propri di un orario.

Livello 1 — Il repertorio della scuola

Il repertorio della scuola contiene ciò che è vero per l'istituto, indipendentemente da un orario: il catalogo delle materie, la directory degli utenti, il calendario degli anni scolastici.

Materie — SubjectFull / Subject / Family

Una materia personalizzata (SubjectFull) estende la materia di base (Subject: name, short, code, type, _extids) con parent, family e color. Due origini coesistono a livello scuola: le materie comuni al paese (sola lettura) e le materie personalizzate dell'istituto. Dettagli funzionali: Gestire le materie.

Utenti — User (professori compresi)

Un User è l'entità unica della directory: identità (cognome, nome, idnumber, contatto), autenticazione (login), roles, servizio orario di riferimento (servicehours), disponibilità globale (campo wishes) e placements. Un professore non è un'entità distinta: è un User che ha teacher tra i suoi roles (uno stesso utente può cumulare più ruoli). Il campo placements (indicizzato per anno scolastico) collega uno studente a una class e a dei groups su un periodo. Dettagli: Gestire i professori.

Anni scolastici — SchoolYear / Holiday

Un SchoolYear definisce date_start → date_end, l'elenco delle holidays e le altweeks (settimane alternate). È un quadro temporale, non un contenitore: gli orari vi si dispiegano senza esservi annidati. Si veda Anno scolastico.

Livello 2 — L'orario

Un Timetable è un'unità di pianificazione coerente. Porta la propria copia locale di professori, classi, gruppi e materie — si veda il principio della copia locale in Organizzazione dei dati.

Configurazione — TimetableConfig

Il campo determinante è type: week (settimanale ripetuto), cycle (ciclo multi-giorno, si veda cycle) o calendar (date reali, si veda dates). time_period e time_unit definiscono la trama della griglia; weekdays i giorni lavorativi; date_windows le finestre di vincolo per la generazione automatica.

Siti, aule, risorse

Un TimetableSite (sito) contiene le sue classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) e le sue resources (TimetableResource: number = quantità disponibile, di cui il sistema garantisce la non sovraprenotazione). distances modella i tempi di percorrenza tra siti. Si veda Siti, aule e risorse e Specializzazioni delle aule.

Professori dell'orario — TimetableTeacher

Copia parziale arricchita di un User: solo alcuni campi identificativi vengono ricopiati (first_name, last_name, idnumber), ai quali si aggiungono campi propri della pianificazione (servicehours sovrascrivibile, classroom preferita, wishes per orario). Un virtual_name non vuoto designa un professore virtuale (posto da coprire, senza un User reale dietro).

Classi, materie di classe, gruppi

• TimetableClass: name, level, campus/sites, studentsnb, e tre sottoalberi chiave — subjects, groups, courses.
• TimetableClassSubject: copia locale di una materia (estende Subject) arricchita per la pianificazione — minutes (volume previsto), pweight (peso pedagogico), incompatibilities, teachers predefiniti, specialisation di aula. Assegnare una materia con un tipo di lezione crea una voce distinta per tipo. Si veda Corsi, lezioni, tipi di lezione.
• TimetableClassGroup: un sottoinsieme di una classe. free=true disattiva i conflitti con il resto della classe (gruppo libero); parent stabilisce la gerarchia di gruppi.

Regole tra gruppi — partizioni, allineamenti, gruppi di gruppi

Le relazioni tra gruppi sono portate dal sottoalbero groups dell'orario, in tre forme:

Si veda anche la panoramica Classe, gruppo, sottogruppo.

Livello 3 — Le lezioni

Una lezione (Lesson) è l'unità di insegnamento effettivamente collocata nell'orario: durata, materia, gruppo, professore/i, aula, risorse, posizione e stato. È generata a partire da una materia di classe (si veda il livello 2) e collegata a una classe (class.courses) oppure direttamente all'orario (timetable.lessons) — quest'ultimo caso per i gruppi di gruppi e le lezioni multi-gruppo, trasversali a più classi.

Il nucleo di una lezione

Una lezione porta i campi di pianificazione — duration (in periodi), duration_actual / duration_accounted (minuti reali / fatturati), modality, subject, group, teachers, classroom, resources — ai quali si aggiungono la sua position, il suo status, i suoi memos e un'identità (_id, _osrev). Impostare teachers o classroom a null forza esplicitamente l'assenza di professore o di aula.

Lezioni complesse

Una lezione può raggrupparne altre:

• assoc — lezioni associate: i gruppi si scambiano insieme.
• concat — lezioni concatenate: rigorosamente consecutive.
• weekalt — settimane alternate: una variante di lezione per settimana.

Questi meccanismi coprono le lezioni complesse — si veda Lezioni complesse: alternate, associate, concatenate.

Posizione di una lezione

La position è un oggetto che colloca la lezione nel tempo. Riunisce i campi seguenti:

• position.day — il giorno della lezione, polimorfo a seconda della modalità dell'orario: un nome di giorno (monday…sunday) in modalità settimanale, un numero di giorno di ciclo ("1", "2"…) in modalità ciclica, o una data YYYY-MM-DD in modalità calendario. È un unico e medesimo campo che cambia forma a seconda della modalità; è sempre presente.
• position.period — l'indice della fascia nella griglia oraria. Una lezione senza period né start/end corrisponde a un giorno festivo.
• position.start / position.end — ore esatte di inizio e di fine (HH:MM), per le lezioni fuori griglia o in modalità calendario che non si allineano a una fascia standard.
• position.fixed — booleano (falso per impostazione predefinita): una lezione fissata, che la generazione automatica non sposterà.

Le lezioni di una classe risiedono in class.courses; l'array timetable.lessons porta le lezioni trasversali legate ai gruppi di gruppi.

Identità di una lezione

Ogni lezione porta due campi tecnici di identità, presenti sugli account Premium:

• _id — identificativo stabile, assegnato alla creazione della lezione e immutabile in seguito (combina una marca temporale e un'impronta del contenuto). È la chiave di una lezione per l'editing collaborativo e per uno strumento esterno che segue le lezioni nel tempo. Per le occorrenze ricorrenti di un orario calendario (settimane alternate, concatenazioni, associazioni), l'_id di ogni occorrenza è derivato da quello della lezione di base, che rimane riconoscibile.
• _osrev — token di revisione (blocco ottimistico), incrementato a ogni modifica (marca temporale + indice di modifica), in modo rigorosamente ordinato in ordine alfabetico (il che permette di sapere facilmente se una revisione è più recente di un'altra). Permette all'editing collaborativo di rilevare e fondere le modifiche concorrenti: una revisione client scaduta segnala un conflitto, che il server dirime o fonde invece di sovrascrivere silenziosamente.

Assenze

Le assenze condividono una base comune (Absence: date_start, date_end, reason, hours, comment, stato) declinata per soggetto.

Un'AbsenceTeacher può essere ristretta a determinate subjects/classes e porta un array di regole di sostituzione (substitutes, ciascuna un AbsenceTeacherSubstitute: sostituto, periodo, fasce orarie, classi e materie coperte). Gli stati differiscono per soggetto (ad esempio ok/aborted per una classe). Si veda la voce di glossario Sostituzione / Supplenza e il modulo Gestione delle assenze.

Membri del personale

Modulo distinto (venduto anche in autonomo) per la sorveglianza e i servizi di vigilanza.

Una StaffingGrid è il modello (giorni, periodi); gli assignments descrivono i posti (req/ideal, priority, needs dettagliati per fascia oraria tramite StaffingNeedSpan); lo schedule concretizza i turni effettivi per data. Si veda il modulo Servizio del personale.

Eventi

Un Event è una voce di agenda posta sopra la griglia: qualcosa che accade nell'istituto senza essere una lezione regolare — un consiglio di classe, un colloquio genitori-professori, un esame su una giornata, un'uscita, una giornata di porte aperte. Gli eventi sono raccolti nel dizionario events (chiavi event-<n>) e fanno parte delle funzionalità Premium.

Campi di un Event (obbligatori: title, start, end):

• title — titolo visualizzato.
• start / end — inizio e fine, nel formato YYYYMMDDTHHmmSS.
• rrule — regola di ricorrenza eventuale.
• attendees — partecipanti: un utente, una classe, un gruppo, un' etichetta libera (custom), oppure l'intero istituto (everybody) / qualunque persona volontaria (anyone).
• location — luogo/luoghi: un'aula dell'orario o un'etichetta libera.
• resources — risorse riservate per l'evento.
• videolink — link di videoconferenza per assistervi a distanza.
• memos — commenti; color — colore (esadecimale).

Il funzionamento sul piano dell'uso (creazione, posa sulla griglia, campi dell'interfaccia) è descritto in Eventi puntuali.

Pannelli informativi

Un Panel è un pannello informativo delle lezioni del giorno (atrio, aula, schermo di accoglienza…). Definisce la selezione delle columns, la topline, i filters/exclusions e delle impostazioni di aspetto. Si veda la voce di glossario Pannello informativo.

Identificativi, copie locali e messa in relazione con un ERP

Per collegare il modello Omniscol a un repertorio esterno, tre principi prevalgono:

1. Le chiavi di dizionario sono gli identificativi stabili. Le materie, gli utenti, i professori, le classi, i gruppi, le aule, le risorse sono indicizzati da un identificativo immutabile (la chiave JSON), e non dalla loro etichetta. È questo perno — mai il name — che occorre utilizzare per qualsiasi corrispondenza.

2. Il campo _extids (ExternalIds) porta gli identificativi esterni. Presente sulle entità sincronizzabili (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), associa a ogni entità i suoi identificativi nei sistemi terzi, ad esempio { "auriga": "12345", "aimaira": "67890" }. È il punto di ancoraggio canonico di un appaiamento bidirezionale.

3. La copia locale scuola ↔ orario è volontaria. Una materia di classe o un professore di orario è una copia arricchita, non un riferimento vivo. Un repertorio esterno deve quindi decidere a quale livello si appaia: il repertorio della scuola (catalogo durevole) o un orario preciso (pianificazione datata). Il dettaglio delle regole di propagazione figura in Organizzazione dei dati.

La configurazione di sincronizzazione risiede in config.extsync (SchoolConfigExtsync): systems (connettori configurati), sync (direzione ed entità), export e schedules, oltre a tabelle di corrispondenza (mappings) per chiave e identificativo Omniscol. Sul piano dell'accesso programmatico, l'API REST e i token sono descritti in Token API; i connettori di sincronizzazione in Sincronizzazione esterna.

La forma esatta ed esaustiva di ogni campo resta definita dallo schema JSON di riferimento dell'account (https://api.omniscol.com/api/guest/school_schema.json, visualizzatore leggibile su omniscol.com/it/datamodel). In caso di divergenza tra questa pagina e lo schema, fa fede lo schema.