Pełny model danych: jednostki JSON, relacje i ontologia

Ta strona opisuje pełny model danych konta Omniscol: jednostki, ich główne pola i ich relacje. Jest rozwinięciem strony koncepcyjnej Organizacja danych, która wyjaśnia dlaczego (baza referencyjna szkoły ↔ plan lekcji, lokalne kopie); tutaj celem jest co — użyteczna mapa struktury, przydatna zwłaszcza do powiązania modelu z zewnętrzną bazą referencyjną (system ERP, katalog użytkowników, system informatyczny).

Strona techniczna. Ten materiał jest przeznaczony do integracji i do dopasowania z systemem zewnętrznym. Nie jest potrzebny do bieżącej pracy z Omniscol: aby zrozumieć organizację danych po stronie funkcjonalnej, zob. Organizacja danych.

Wszystkie dane placówki są zorganizowane w formie drzewa. Opisane poniżej jednostki (użytkownicy, lata szkolne, plany lekcji, nieobecności, wydarzenia itd.) odpowiadają poszczególnym gałęziom tej struktury. Odniesieniem normatywnym jest schemat JSON konta. Można go przeglądać w dwóch postaciach:

• źródło surowe (schemat JSON jako taki), udostępniane przez konto pod adresem https://api.omniscol.com/api/guest/school_schema.json;
• czytelna przeglądarka drzewa pod adresem omniscol.com/pl/datamodel (oraz odpowiadająca jej dokumentacja API pod adresem omniscol.com/pl/developers).

Ten schemat opisuje dokładnie fizyczny sposób przechowywania danych w bazie, w postaci dokumentu JSON. Ta strona przedstawia jego uporządkowaną i stabilną w czasie wykładnię.

Dokument szkoły: korzeń

Dokument w korzeniu skupia trwałą bazę referencyjną placówki oraz całe jej planowanie. Jego poddrzewa pierwszego poziomu:

Poddrzewa opisane jako „słownik” są obiektami JSON, których klucze są stabilnymi identyfikatorami (punkt odniesienia dla każdego powiązania zewnętrznego — zob. sekcja końcowa).

Pola przekrojowe: _extids i wishes

Dwa pola powtarzają się w wielu jednostkach. Aby nie opisywać ich w każdym schemacie, są opisane jeden raz tutaj.

• _extids (ExternalIds) — tabela identyfikatorów jednostki w systemach zewnętrznych, na przykład { "auriga": "12345" }. Obecne w jednostkach podlegających synchronizacji (przedmioty, rodziny, użytkownicy, lokalizacje, sale, zasoby, nauczyciele, klasy, grupy…). To punkt zakotwiczenia powiązania z zewnętrzną bazą referencyjną (zob. sekcja końcowa).
• wishes — ograniczenia czasowe: dostępność, przedziały czasowe pożądane lub do unikania, maksymalna liczba godzin, uprzywilejowana sala… Obecne w większości jednostek podlegających planowaniu: użytkownicy, nauczyciele planu lekcji, kursy (przedmioty klas), grupy, klasy, sale, przedziały godzinowe lokalizacji, siatki nadzoru. W zależności od zakresu te ograniczenia są globalne (poziom szkoły) albo właściwe dla jednego planu lekcji.

Poziom 1 — Baza referencyjna szkoły

Baza referencyjna szkoły zawiera to, co jest prawdą dla placówki niezależnie od planu lekcji: katalog przedmiotów, spis użytkowników, kalendarz lat szkolnych.

Przedmioty — SubjectFull / Subject / Family

Przedmiot niestandardowy (SubjectFull) rozszerza przedmiot podstawowy (Subject: name, short, code, type, _extids) o pola parent, family i color. Na poziomie szkoły współistnieją dwa źródła: przedmioty wspólne dla kraju (tylko do odczytu) oraz przedmioty niestandardowe placówki. Szczegóły funkcjonalne: Zarządzanie przedmiotami.

Użytkownicy — User (w tym nauczyciele)

User to jedyna jednostka spisu użytkowników: tożsamość (nazwisko, imię, idnumber, kontakt), uwierzytelnianie (login), roles, referencyjne godziny pracy (servicehours), globalna dostępność (pole wishes) oraz placements. Nauczyciel nie jest odrębną jednostką: to User, który ma teacher wśród swoich roles (ten sam użytkownik może łączyć kilka ról). Pole placements (indeksowane rokiem szkolnym) przypisuje ucznia do klasy (class) i do grup (groups) na dany okres. Szczegóły: Zarządzanie nauczycielami.

Lata szkolne — SchoolYear / Holiday

SchoolYear wyznacza date_start → date_end, listę holidays oraz altweeks (tygodnie naprzemienne). Jest ramą czasową, nie pojemnikiem: plany lekcji rozkładają się w niej, nie będąc w niej zagnieżdżone. Zob. Rok szkolny.

Poziom 2 — Plan lekcji

Timetable to spójna jednostka planowania. Zawiera własną lokalną kopię nauczycieli, klas, grup i przedmiotów — zob. zasadę lokalnej kopii na stronie Organizacja danych.

Konfiguracja — TimetableConfig

Polem decydującym jest type: week (powtarzalny tygodniowy), cycle (cykl wielodniowy, zob. cycle) albo calendar (rzeczywiste daty, zob. dates). time_period i time_unit definiują ramę siatki godzin; weekdays — dni robocze; date_windows — okna ograniczeń dla generowania.

Lokalizacje, sale, zasoby

TimetableSite (lokalizacja) zawiera swoje classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) oraz swoje resources (TimetableResource: number = dostępna ilość, której przekroczenia system nie dopuszcza). distances odwzorowuje czasy przejazdu między lokalizacjami. Zob. Lokalizacje, sale i zasoby oraz Specjalizacje sal.

Nauczyciele planu lekcji — TimetableTeacher

Uzupełniona kopia częściowa jednostki User: kopiowane są tylko niektóre pola identyfikacyjne (first_name, last_name, idnumber), do których dochodzą pola właściwe dla planowania (servicehours do nadpisania, uprzywilejowana classroom, wishes w ramach planu lekcji). Niepuste virtual_name oznacza wirtualnego nauczyciela (stanowisko do obsadzenia, bez rzeczywistego User w tle).

Klasy, przedmioty klas, grupy

• TimetableClass: name, level, campus/sites, studentsnb oraz trzy kluczowe poddrzewa — subjects, groups, lessons.
• TimetableClassSubject: lokalna kopia przedmiotu (rozszerza Subject), uzupełniona na potrzeby planowania — minutes (docelowa liczba godzin), pweight (waga pedagogiczna), incompatibilities, domyślni teachers, specialisation sali. Przypisanie przedmiotu z typem lekcji tworzy odrębny wpis dla każdego typu. Zob. Kursy, lekcje, typy lekcji.
• TimetableClassGroup: podzbiór klasy. free=true wyłącza konflikty z pozostałą częścią klasy (grupa wolna); dzięki polu parent powstaje hierarchia grup.

Reguły między grupami — podziały klasy, wyrównania, grupy grup

Relacje między grupami są przechowywane w poddrzewie groups planu lekcji, w trzech postaciach:

Zob. także przegląd ogólny Klasa, grupa, podgrupa.

Poziom 3 — Lekcje

Lekcja (Lesson) to jednostka nauczania faktycznie umieszczona w planie lekcji: czas trwania, przedmiot, grupa, nauczyciel(e), sala, zasoby, pozycja i status. Jest tworzona na podstawie przedmiotu klasy (zob. poziom 2) i przypisana albo do klasy (class.lessons), albo bezpośrednio do planu lekcji (timetable.lessons) — ten drugi przypadek dotyczy grup grup oraz lekcji wielogrupowych, przekrojowych wobec kilku klas.

Rdzeń lekcji

Lekcja zawiera pola planowania — duration (w przedziałach czasowych), duration_actual / duration_accounted (minuty rzeczywiste / rozliczane), modality, subject, group, teachers, classroom, resources — do których dochodzą jej position, status, memos oraz tożsamość (_id, _osrev). Ustawienie teachers lub classroom na null jawnie wymusza brak nauczyciela lub sali.

Złożone lekcje

Jedna lekcja może skupiać inne:

• assoc — lekcje skojarzone: grupy wymieniają się razem.
• concat — lekcje połączone: ściśle następujące po sobie.
• weekalt — tygodnie naprzemienne: jeden wariant lekcji na tydzień.

Te mechanizmy obejmują złożone lekcje — zob. Złożone lekcje: naprzemienne, skojarzone, połączone.

Pozycja lekcji

position to obiekt, który umieszcza lekcję w czasie. Skupia następujące pola:

• position.day — dzień lekcji, polimorficzny zależnie od trybu planu lekcji: nazwa dnia (monday…sunday) w trybie tygodniowym, numer dnia cyklu ("1", "2"…) w trybie cyklicznym albo data YYYY-MM-DD w trybie kalendarzowym. To jedno i to samo pole, które zmienia postać zależnie od trybu; jest zawsze obecne.
• position.period — indeks przedziału czasowego w siatce godzin. Lekcja bez period ani start/end odpowiada dniu wolnemu.
• position.start / position.end — dokładne godziny rozpoczęcia i zakończenia (HH:MM), dla lekcji poza siatką albo w trybie kalendarzowym, które nie wpisują się w standardowy przedział czasowy.
• position.fixed — wartość logiczna (domyślnie fałsz): lekcja zablokowana, której generowanie nie przeniesie.

Lekcje klasy znajdują się w class.lessons; tablica timetable.lessons zawiera lekcje przekrojowe, powiązane z grupami grup.

Tożsamość lekcji

Każda lekcja ma dwa techniczne pola tożsamości, obecne na kontach Premium:

• _id — identyfikator stabilny, nadawany przy utworzeniu lekcji i później niezmienny (łączy znacznik czasu i odcisk treści). To klucz lekcji dla współpracy w czasie rzeczywistym i dla zewnętrznego narzędzia, które śledzi lekcje w czasie. W przypadku wystąpień powtarzalnych w kalendarzowym planie lekcji (tygodnie naprzemienne, połączenia, skojarzenia) _id każdego wystąpienia jest pochodną identyfikatora lekcji podstawowej, która pozostaje rozpoznawalna.
• _osrev — token rewizji (blokowanie optymistyczne), zwiększany przy każdej zmianie (znacznik czasu + numer zmiany), w porządku ściśle alfabetycznym (co pozwala łatwo stwierdzić, czy jedna rewizja jest nowsza od innej). Pozwala on współpracy w czasie rzeczywistym wykrywać i scalać równoczesne zmiany: nieaktualna rewizja po stronie klienta sygnalizuje konflikt, który serwer rozstrzyga lub scala, zamiast po cichu nadpisać dane.

Nieobecności

Nieobecności mają wspólną podstawę (Absence: date_start, date_end, reason, hours, comment, status), doprecyzowaną osobno dla każdego podmiotu.

Jednostkę AbsenceTeacher można ograniczyć do wybranych subjects/classes; zawiera ona tablicę reguł zastępstwa (substitutes, każda to AbsenceTeacherSubstitute: zastępca, okres, przedziały czasowe, objęte klasy i przedmioty). Statusy różnią się zależnie od podmiotu (na przykład ok/aborted dla klasy). Zob. hasło słownika Zastępstwo oraz moduł Zarządzanie nieobecnościami.

Członkowie personelu

Odrębny moduł (sprzedawany także samodzielnie) do nadzoru i do dyżurów opiekuńczych.

StaffingGrid to wzorzec (dni, przedziały czasowe); assignments opisują stanowiska (req/ideal, priority, needs wyszczególnione według przedziału przez StaffingNeedSpan); schedule materializuje faktyczne dyżury według daty. Zob. moduł Obsada personelu.

Wydarzenia

Event to wpis kalendarza nałożony na siatkę godzin: coś, co odbywa się w placówce, nie będąc regularną lekcją — posiedzenie rady pedagogicznej, zebranie z rodzicami, całodzienny egzamin, wycieczka, dzień otwarty. Wydarzenia są przechowywane w słowniku events (klucze event-<n>) i należą do funkcji Premium.

Pola jednostki Event (obowiązkowe: title, start, end):

• title — wyświetlana nazwa.
• start / end — początek i koniec, w formacie YYYYMMDDTHHmmSS.
• rrule — ewentualna reguła powtarzalności.
• attendees — uczestnicy: użytkownik, klasa, grupa, dowolna nazwa (custom) albo cała placówka (everybody) / każda osoba chętna (anyone).
• location — miejsce (miejsca): sala z planu lekcji albo dowolna nazwa.
• resources — zasoby zarezerwowane na wydarzenie.
• videolink — link do wideokonferencji, aby uczestniczyć zdalnie.
• memos — komentarze; color — kolor (szesnastkowy).

Działanie po stronie użytkowania (tworzenie, umieszczanie na siatce godzin, pola interfejsu) opisuje strona Wydarzenia jednorazowe.

Panele informacyjne

Panel to panel informacyjny pokazujący lekcje danego dnia (hol, sala, ekran w recepcji…). Definiuje wybór columns, topline, filters/exclusions oraz ustawienia wyglądu. Zob. hasło słownika Panel informacyjny.

Identyfikatory, lokalne kopie i powiązanie z systemem ERP

Aby powiązać model Omniscol z zewnętrzną bazą referencyjną, obowiązują trzy zasady:

1. Klucze słowników są stabilnymi identyfikatorami. Przedmioty, użytkownicy, nauczyciele, klasy, grupy, sale i zasoby są indeksowane niezmiennym identyfikatorem (kluczem JSON), a nie swoją nazwą. To ten punkt odniesienia — nigdy name — należy wykorzystywać do każdego odwzorowania.

2. Pole _extids (ExternalIds) zawiera identyfikatory zewnętrzne. Obecne w jednostkach podlegających synchronizacji (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), przypisuje każdej jednostce jej identyfikatory w systemach zewnętrznych, na przykład { "auriga": "12345", "aimaira": "67890" }. To kanoniczny punkt zakotwiczenia powiązania dwukierunkowego.

3. Lokalna kopia szkoła ↔ plan lekcji jest celowa. Przedmiot klasy albo nauczyciel planu lekcji to uzupełniona kopia, a nie żywe odniesienie. Zewnętrzna baza referencyjna musi więc zdecydować, na jakim poziomie się dopasowuje: do bazy referencyjnej szkoły (trwały katalog) albo do konkretnego planu lekcji (datowane planowanie). Szczegóły reguł propagacji znajdują się na stronie Organizacja danych.

Konfiguracja synchronizacji znajduje się w config.extsync (SchoolConfigExtsync): systems (skonfigurowane konektory), sync (kierunek i jednostki), export oraz schedules, a także tabele odwzorowań (mappings) według klucza i identyfikatora Omniscol. Po stronie dostępu programowego interfejs REST i tokeny opisują Tokeny API; konektory synchronizacji — Synchronizacja zewnętrzna.

Dokładna i wyczerpująca postać każdego pola pozostaje zdefiniowana w referencyjnym schemacie JSON konta (https://api.omniscol.com/api/guest/school_schema.json, czytelna przeglądarka pod adresem omniscol.com/pl/datamodel). W razie rozbieżności między tą stroną a schematem rozstrzyga schemat.