Linee guida per l'onboarding per i provider di API OneRoster con School Data Sync (SDS)

  • Articolo

Introduzione

Microsoft School Data Sync (SDS) è in grado di sincronizzare le informazioni di identità e roster da qualsiasi sistema che implementa lo standard 1EdTech OneRoster API (Application Programming Interfaces) in un flusso di dati in ingresso. Questo documento ha lo scopo di aiutare tutti i nuovi provider di API OneRoster a integrarsi correttamente con SDS. Il processo di onboarding seguente definisce i passaggi richiesti dal provider di API prima che possano essere aggiunti per consentire ai tenant di selezionare e usare in SDS.

Informazioni su SDS

Panoramica

  1. Completare il modulo nel modulo di iscrizione ai partner SDS.

    1. Indicare che è necessario assistenza per l'integrazione della sincronizzazione dati dell'istituto di istruzione nel modulo.

    2. La registrazione è necessaria per accedere al modulo: visitare il sito Microsoft Partner Network per altre informazioni. È necessario inviare un modulo separato per l'accesso alle risorse di sviluppo di SDS e Office.

  2. Implementare gli endpoint dell'API OneRoster richiesti da SDS.

    SDS usa un filtro sulla proprietà dateLastModified per l'elaborazione di sincronizzazione differenziale/sincronizzazione incrementale ed è necessario per l'integrazione con SDS.

  3. Verificare che SDS funzioni con gli endpoint dell'API OneRoster.

    1. Valutare le API usando la raccolta Postman.

    2. Eseguire il test con la progettazione di SDS in un ambiente sandbox.

    3. Configurare SDS per convalidare la soluzione E2E.

  4. Pilotare la soluzione con due clienti di produzione.

  5. Rendere il connettore disponibile a livello generale in SDS per tutti i tenant EDU Office 365.

Introduzione

Endpoint API necessari per SDS

Azione URL Proprietà filtro necessarie Filtro facoltativo/consigliato Esempi
GetAllAcademicSessions /academicSessions stato dateLastModified /academicSessions?offset=0&limit=5000&filter=status='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}'
GetAllOrgs /Org stato dateLastModified /orgs?offset=0&limit=5000&filter=status='active'/orgs?filter=dateLastModified>'{deltaDateTime}'
GetAllUsers /Gli utenti stato dateLastModified /users?offset=0&limit=5000&filter=status='active'/users?filter=dateLastModified>'{deltaDateTime}'
GetAllClasses /Classi stato dateLastModified /classes?offset=0&limit=5000&filter=status='active'/classes?filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments /Iscrizioni stato dateLastModified /enrollments?offset=0&limit=5000&filter=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}'

Endpoint API facoltativi per SDS

Nota

Per i dati facoltativi per i dati demografici, le relazioni di contatto degli studenti e i flag utente degli studenti, la possibilità per un cliente di includere o meno questi dati si baserà sulle funzionalità di dati facoltative supportate dal profilo del provider che verrà creato. Seguendo i passaggi di test e verifica annotati, se si sceglie di supportare anche questi dati per i clienti che usano SDS, verrà visualizzato l'interruttore (impostazione predefinita) selezionato Sì per includere dati aggiuntivi. Possono selezionare l'interruttore per disattivare se lo desiderano. Se l'interruttore non è disponibile, visualizzato ma disattivato e non è disponibile per l'interazione, significa che il profilo del provider non supporta attualmente la fornitura di tali dati.

Azione URL Proprietà filtro necessarie Filtro facoltativo/consigliato Esempi
GetAllCourses /Corsi stato dateLastModified /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics /Demografia stato dateLastModified /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}'

Relazioni di contatto facoltative tra studenti utente

La relazione di contatto tra studenti può essere specificata per consentire agli utenti degli studenti di migliorare le esperienze di docente per la comunicazione con i genitori e i tutori degli studenti. I contatti sono più utenti forniti con /users e l'associazione a uno studente si trovano nel record utente dello studente in "agenti".

  • Per altre informazioni, sui ruoli di relazione di contatto degli studenti supportati da SDS, vedere Elenco predefinito dei valori: Ruoli di relazione di contatto.
  • FamilyName, givenName e posta elettronica sono necessari per gli utenti con ruoli di contatto/tutore.
  • Aspettatevi che telefono e sms siano in E.164 e + devono essere inclusi. (Esempio: +1234567890).
  • Se vengono forniti dati inversi, da un record di controllo della relazione di contatto a uno studente nel campo "agenti" degli utenti di contatto, questi record vengono filtrati.

Flag facoltativi per i dati demografici degli utenti

I flag utente possono essere specificati per consentire agli utenti degli studenti di indicare la loro partecipazione a un programma o a una coorte. I flag utente sono inclusi (se true per l'utente) o non inclusi se non applicabile.

I flag vengono specificati come estensione di metadati per l'utente, in un campo di metadati, seguendo una chiave|Coppia di valori, con la chiave denominata microsoft.userFlags e deve essere formattata come elenco delimitato da virgole. I flag utente possono essere visualizzati in qualsiasi ordine e non fanno distinzione tra maiuscole e minuscole.

Per altre informazioni, nell'elenco predefinito dei valori dei flag utente supportati da SDS, vedere Elenco predefinito di valori: Flag utente.

Esempio:

{ 
  "user" : { 
   … 
   … 
    "metadata" : { 
     "microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“ 
    } 
}

Regole di corrispondenza e convalida dei dati

Per altre informazioni sulla corrispondenza dei dati e sulle regole di convalida, vedere Regole e descrizioni di convalida.

Importante

Per 1EdTech è responsabilità del provider imporre la privacy dei dati per i dati disponibili quando viene effettuata una richiesta di dati. School Data Sync effettua una richiesta di dati attivi in base all'ora della richiesta.

Note e suggerimenti utili

  • Gli endpoint vengono sempre dopo l'URL https: {server_URL}/ims/esistenti/v1p1.

  • Tutti gli endpoint devono supportare il paging, ovvero i parametri limite e offset (ad esempio: limite=10&offset=5000).

  • Gli endpoint hanno requisiti per il supporto dei parametri di filtro per consentire il filtro in base allo stato o per abilitare la sincronizzazione differenziale.

  • I clienti sanno come abilitare l'opzione "È attivo" o come consentire solo la disponibilità di dati attivi per la connessione che deve essere usata da School Data Sync. Ciò garantisce che vengano forniti solo i dati attivi per l'anno scolastico e la sessione attiva man mano che l'anno scolastico progredisce.

  • SDS applica un filtro alla proprietà dateLastModified per l'elaborazione di sincronizzazione differenziale/sincronizzazione incrementale ed è necessario per l'integrazione con SDS.

  • I provider devono scegliere di implementare lo schema di autenticazione OAuth1(a) o OAuth 2.0 (concessione delle credenziali client), oAuth 2.0 preferito.

  • Durante lo sviluppo, è possibile verificare gli endpoint con la raccolta Postman.

  • Se il protocollo di autenticazione supportato è "OAuth 2" - tipo di concessione delle credenziali client, SDS invierà le credenziali nell'intestazione "Autorizzazione". SDS non supporta l'invio delle credenziali nel corpo della richiesta.

Test delle API OneRoster

Uso della raccolta Postman

Postman è uno strumento noto per eseguire e gestire le API REST. È stata creata la raccolta Postman dell'API OneRoster per richiamare e testare le API OneRoster richieste da SDS. L'esecuzione della raccolta richiama tutte le API richieste da SDS ed esegue test semplici sui dati restituiti.

Testare con SDS Engineering in un ambiente sandbox

Creare un ambiente sandbox per le API OneRoster e condividere le credenziali con il tecnico SDS designato. Insieme, viene eseguito un set più approfondito di test per garantire che l'integrazione riesca.

Configurare per convalidare la soluzione

Quando tutti i test hanno avuto esito positivo, il nome del sistema viene aggiunto all'elenco dei provider OneRoster in SDS, ma è visibile solo per i tenant in anteprima per i profili dei provider indicati come modalità "InPilot" (non disponibile pubblicamente). Successivamente, si eseguirà l'onboarding di SDS configurando l'inserimento dei dati con l'API OneRoster nel tenant di Microsoft 365 di test per sincronizzare i dati dagli endpoint OneRoster sandbox e assicurarsi che le esecuzioni vengano completate senza errori. Se vengono visualizzati errori o avvisi e si necessita di assistenza dopo l'analisi automatica, contattare il tecnico SDS designato.

Progetto pilota del cliente

Dopo aver completato correttamente i test, è il momento di iniziare a pilotare la soluzione con i clienti. Il nome del sistema sarà visibile nell'elenco dei provider OneRoster® in SDS per quelli "in anteprima" per visualizzare anche i provider che sono in modalità "InPilot", dopo aver accettato di pilotare l'integrazione. Il team SDS e il team del provider OneRoster collaboreranno per identificare i clienti pilota appropriati e pianificare un tempo per distribuire SDS. Collaboreremo a stretto contatto con i clienti per garantire che le esecuzioni del flusso in ingresso siano riuscite e convalidare i risultati insieme. Eventuali bug finali identificati devono essere risolti prima di rendere la soluzione disponibile pubblicamente a tutti i clienti Office 365 dell'istruzione.

Vai pubblico

Dopo che due clienti hanno completato correttamente le distribuzioni pilota, il sistema partner sarà disponibile in SDS come sistema di origine del provider OneRoster certificato. SDS visualizzerà il nome del provider ai tenant durante la configurazione dell'inserimento dati con l'API OneRoster. Il team SDS documenterà anche il sistema partner nella pagina di panoramica del provider di API OneRoster nei documenti online di SDS.

Il team SDS avrà bisogno di:

  • Versione minima del software
  • Prerequisiti di configurazione
  • Come ottenere ID client, segreto client e URL
  • Qualsiasi altra istruzione specifica
  • Chi contattare per assistenza

Il team SDS si coordinerà anche con il team per promuovere l'integrazione in modo più ampio attraverso vari canali di marketing.