Personalizzazione dell'API: override degli endpoint e hook

Dove trovarlo

Modulo Amministrazione, schermata Importare/Esportare, sezione API tweaks, pulsante API.

La schermata è riservata ai conti Premium e protetta da un'autenticazione rafforzata: Omniscol richiede nuovamente la password dell'amministratore prima di aprire la finestra. Poiché ogni azione su questa schermata tocca il contratto tecnico della Sua integrazione, la sua messa in opera avviene in collaborazione con Omniscol.

Configurazione generale

Qui definisce delle intestazioni HTTP (formato chiave1:valore1;chiave2:valore2) applicate a tutti gli hook. È il luogo naturale per veicolare un token di autenticazione verso il Suo server (ad esempio un Authorization: Bearer … che il Suo server si attende). Per un override, l'autenticazione va invece nelle intestazioni proprie dell'endpoint (vedi sotto).

Override di un endpoint

Un override ridefinisce un endpoint dell'API di Omniscol affinché l'applicazione web chiami un altro URL al suo posto. Tre usi, dal più potente al più semplice.

Servire un dato in diretta dal Suo sistema informativo

È l'uso più potente. Reindirizza un endpoint in lettura verso un URL esterno — tipicamente un ETL che si interfaccia con il sistema informativo interno del Suo istituto. L'applicazione web va allora a cercare il dato in diretta in quel sistema, invece che nella copia locale detenuta da Omniscol.

Concretamente: quando l'URL di reindirizzamento è un indirizzo esterno assoluto, l'applicazione web lo chiama direttamente, senza ripassare per i server di Omniscol, e consuma la risposta così com'è — esattamente come se provenisse da Omniscol. L'unico vincolo è che il Suo sistema risponda nel formato atteso da Omniscol per quell'endpoint (stessa struttura JSON): non c'è alcuna transcodifica intermedia. Per quell'endpoint, la copia locale di Omniscol non è più interrogata; il dato visualizzato è quello, vivo, del Suo sistema.

Esempio: il catalogo delle materie dell'istituto servito al volo dal Suo sistema informativo, in modo che ogni aggiornamento lato scuola sia visibile immediatamente in Omniscol, senza reimportazione.

L'autenticazione verso il Suo sistema va qui nelle intestazioni proprie dell'endpoint (ad esempio un Authorization: Bearer …), inserite sulla riga dell'override. Anche il metodo HTTP può essere imposto per endpoint.

Ricollegare un endpoint dell'applicazione stessa a una fonte esterna viva è una possibilità tanto potente quanto esigente: da maneggiare con il Suo servizio informatico, e in collaborazione con Omniscol.

Interporre il Suo server o un proxy

Può anche far passare le chiamate attraverso il Suo server o un proxy — ad esempio per autorizzare la condivisione di risorse tra origini (CORS), oppure per interporre una logica interna tra l'applicazione web e Omniscol.

Disattivare un endpoint

Disattiva un endpoint non assegnandogli alcun URL di reindirizzamento (metodo null).

Valuti l'effetto sull'interfaccia. Omniscol è un'applicazione web a pagina singola (SPA) i cui elementi di interfaccia sono pilotati dagli endpoint disponibili: pulsanti, schede e menu si mostrano solo se l'endpoint da cui dipendono esiste. Disattivare un endpoint fa quindi scomparire dinamicamente, alla successiva visualizzazione, gli elementi di interfaccia che ne dipendono — e se disattiva tutti gli endpoint di un modulo, è il modulo intero a scomparire dalla navigazione. Questi elementi sono rimossi, non semplicemente nascosti, e il tutto avviene senza alcun intervento sul codice: basta modificare la configurazione e ricaricare l'applicazione.

La tabella elenca, per endpoint: la sua chiave (il codice interno dell'operazione), il suo URL di origine, il metodo HTTP, il nuovo URL di reindirizzamento e delle intestazioni specifiche. Un campo di ricerca permette di ritrovare l'endpoint da sovrascrivere.

Hook (chiamate in uscita)

Un hook chiede a Omniscol di inviare una richiesta HTTP al Suo URL dopo che un'operazione è riuscita. È il meccanismo per tenere un sistema esterno aggiornato in tempo reale — un pannello informativo, uno spazio digitale di lavoro, un sistema di risorse umane, una sincronizzazione interna…

Un hook si collega in due modi:

• a un endpoint preciso (la chiave dell'operazione);
• a un evento raggruppato, che copre in una volta una famiglia di operazioni. Esistono tre eventi raggruppati:
  • modifica di orario (creazione, spostamento o eliminazione di lezioni, attivazione di un orario, e assenze di professore o di classe non appena una data viene toccata);
  • modifica di un professore (aggiunta, aggiornamento o eliminazione);
  • modifica di una materia (materie personalizzate).

Per ogni hook, inserisce l'URL di callback, il metodo HTTP, la casella «con dati» (occorre allegare il corpo della richiesta originale?) e delle intestazioni proprie.

Ciò che il Suo server riceve

La chiamata è inviata in application/json e porta, oltre alle Sue intestazioni:

• il corpo della richiesta originale se l'opzione «con dati» è attivata;
• un blocco di metadati Omniscol: l'URL chiamato, il codice dell'endpoint, il metodo, i parametri, il token di autenticazione dell'utente e l'identificativo dell'istituto;
• intestazioni di tracciabilità: X-OS-original-query, X-OS-original-endpoint, X-OS-auth e X-School.

Per l'evento modifica di orario, quando l'opzione «con dati» è attiva, la chiamata include in più un differenziale delle lezioni (lezioni aggiunte, modificate, eliminate) — pratico per propagare solo ciò che è cambiato.

Comportamento

Gli hook partono in background, dopo che l'operazione dell'utente è andata a buon fine: non rallentano l'interfaccia e non la bloccano in caso di errore del Suo server. Una chiamata in uscita che non va a buon fine viene registrata, senza interrompere il lavoro in Omniscol. Ogni chiamata ha un breve tempo di scadenza (qualche secondo): il Suo server deve confermare la ricezione rapidamente e trattare il resto dal proprio lato.

Da sapere

• L'API di Omniscol espone un sottoinsieme di operazioni; un override o un hook si applica solo agli endpoint effettivamente esposti. Vedi API Omniscol per l'elenco e l'autenticazione.
• Per un'integrazione con un software gestionale (ERP, sistema HR, spazio digitale di lavoro), la sincronizzazione dedicata è spesso più adatta — vedi Sincronizzazione con sistemi esterni. Internamente, si utilizza lo stesso sistema di hook.
• Affinché un agente IA consulti i Suoi dati senza sviluppo, vedi MCP — collegare un agente IA esterno.