Come distribuire School Data Sync usando l'API SIS powerschool

Importante

L'esperienza school Data Sync (classica) verrà sostituita dalla nuova esperienza school Data Sync entro la fine del 2024. Ti consigliamo di iniziare a pianificare la transizione alla nuova esperienza per il tuo prossimo anno torna a scuola.

PowerSchool è un sistema informativo per studenti (SIS) che si integra con School Data Sync (classico). Usando il metodo di sincronizzazione dell'API PowerSchool, è possibile connettersi direttamente al SIS usando le API basate su REST e sincronizzare i dati direttamente anziché usare file CSV. L'API PowerSchool per inserire le categorie di dati evidenziate consente di illuminare le funzionalità SDS di base (versione classica) per il provisioning. Consente inoltre di migliorare le esperienze per i prodotti e le funzionalità di Microsoft 365 (Microsoft 365) elencati.

Per configurare SDS usando il metodo PowerSchool Sync, seguire le istruzioni descritte in dettaglio in questo articolo.

Prerequisiti

Prima di iniziare a eseguire la sincronizzazione con SDS (versione classica) usando il metodo OneRoster® Sync, leggere La panoramica di SDS (versione classica) e assicurarsi di soddisfare i prerequisiti seguenti:

• Un tenant di Office 365 per Education
• Autorizzazioni Amministrazione globali

Video sulla distribuzione

Per informazioni sulla corrispondenza delle identità utente, vedere anche il video seguente.

• Video: Come trovare la corrispondenza tra gli attributi di origine e di destinazione per la sincronizzazione

Installare il plug-in API REST per PowerSchool

Prima che SDS (classico) possa accedere ai dati dal SIS di PowerSchool, è necessario installare il plug-in dell'applicazione all'interno di PowerSchool e ottenere le credenziali OAuth.

1. Nel computer locale creare un file di installazione del plug-in XML usando il Blocco note copiando il contenuto seguente. Salvare il file come "plugin.xml".

   <?xml version="1.0" encoding="UTF-8"?>
   <plugin xmlns="http://plugin.powerschool.pearson.com"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://plugin.powerschool.pearson.com plugin.xsd"
   name="Microsoft School Data Sync"
   version="1.0.0"
   description="Plugin for Powerschool REST API for Microsoft SDS">
   <oauth></oauth>
   <publisher name="Microsoft Corp.">
   <contact email="sdshelp@microsoft.com" />
   </publisher>  
   </plugin>
   

2. Accedere al sito Web del portale di amministrazione di PowerSchool usando le credenziali di amministratore di sistema.

3. Nella pagina iniziale scegliere Sistema dal menu principale, quindi passare a Impostazioni > di sistemaInstallazioneconfigurazione> gestione plug-in

4. Immettere o selezionare il file di installazione del plug-in creato (.xml) e quindi scegliere Installa. Il plug-in viene visualizzato nella sezione Plug-in installati nella pagina Dashboard di gestione plug-in . Assicurarsi che il plug-in sia abilitato. In caso contrario, scegliere l'opzione Abilita nella pagina Dashboard di gestione plug-in .

5. Nella pagina Dashboard di gestione plug-in verificare che il plug-in sia abilitato.

6. Scegliere Configurazione dati per visualizzare le credenziali OAuth generate per il plug-in.

7. Registrare i valori per l'ID client e il segreto client in modo da poter immettere queste credenziali quando si crea il profilo di sincronizzazione.

Dati accessibili dalla sincronizzazione dati dell'istituto di istruzione (versione classica)

Importante

Connettendo e rendendo disponibili i dati dell'istituto con School Data Sync (versione classica), si riconosce di essere autorizzati a condividere questi dati con Microsoft e di impegnarsi a rispettare gli standard di governance dei dati dell'organizzazione.

Di seguito sono riportate le richieste URL Microsoft e le risposte di PowerSchool (a partire dal 1° giugno 2023). Questi potrebbero cambiare in futuro.

Scuola

Richiesta URL Microsoft

~/ws/v1/district/school?page{1}&pageSize={100}

~/ws/v1/school/{id}

Risposta di PowerSchool

    { 
     "school": { 
       "@expansions": "school_boundary, full_time_equivalencies, school_fees_setup", 
       "id": , 
       "name": "", 
       "school_number": , 
       "low_grade": , 
       "high_grade": , 
       "alternate_school_number": , 
       "addresses": { 
         "physical": { 
         "street": "", 
         "city": "", 
         "state_province": "", 
         "postal_code": "" 
        } 
      }, 
      "phones": { 
        "main": { 
        "number": "" 
        } 
      }, 
      "principal": { 
      "name": { 
        "first_name": "", 
        "middle_name": "" 
        } 
      } 
     } 
    } 

Sezioni per la scuola

Richiesta URL Microsoft

~/ws/v1/school/{id}/section?pagesize=100&page=1&expansions=term&q=term.start_year==2022

Risposta di PowerSchool

   { 
     "sections": { 
      "@expansions": "term", 
      "section": [ 
     { 
       "id": , 
       "school_id": , 
       "course_id": ,
       "term_id": , 
       "term": { 
          "id": , 
          "local_id": , 
          "school_id": , 
          "start_year": , 
          "portion": , 
          "start_date": "", 
          "end_date": "", 
          "abbreviation": "", 
          "name": "" 
        }, 
       "section_number": ,
       "expression": "",
       "external_expression": "",
       "staff_id": ,
       "gradebooktype": ""
      }
     }
    } 

Corsi per la scuola

Richiesta URL Microsoft

~/ws/v1/school/{id}/course?pagesize=100&page=1

Risposta di PowerSchool

    { 
     "courses": { 
       "course": [ 
       { 
        "id": , 
        "course_number": "", 
        "course_name": "" 
      } 
     }
    } 

Iscrizioni per l'istituto di istruzione

Richiesta URL Microsoft

~/ws/v1/section/{id}/section_enrollment?pagesize=100&page=1

Risposta di PowerSchool

    { 
     "section_enrollments": { 
       "section_enrollment": [ 
       { 
        "id": , 
        "section_id": , 
        "student_id": , 
        "entry_date": "", 
        "exit_date": "", 
        "dropped":  
       } 
      }
    }

Studenti per la scuola

Richiesta URL Microsoft

~/ws/v1/school/{id}/student?pagesize=100&page=1&expansions=contact_info,demographics, school_enrollment,student_username&q=school_enrollment.enroll_status==(A,P)

Risposta di PowerSchool

    { 
     "students": { 
     "@expansions": "demographics, addresses, alerts, phones, school_enrollment, ethnicity_race, 
                    contact, contact_info, initial_enrollment, schedule_setup, fees, 
                    lunch, counselors, global_id", 
     "student": [ 
      { 
        "id": , 
        "local_id": , 
        "student_username": "", 
        "name": { 
          "first_name": "", 
          "middle_name": "", 
          "last_name": "" 
        }, 
        "demographics": { 
          "gender": "", 
          "birth_date": "", 
          "district_entry_date": "", 
          "projected_graduation_year":    
        }, 
        "school_enrollment": { 
          "enroll_status": "", 
          "enroll_status_description": "", 
          "enroll_status_code": , 
          "grade_level": , 
          "entry_date": "", 
          "exit_date": "", 
          "school_number": , 
          "school_id": , 
          "entry_code": "", 
          "entry_comment": "", 
          "full_time_equivalency": { 
            "fteid": , 
            "name": "" 
          }  
        }, 
        "contact_info": { 
          "email": "" 
        } 
      } 
     }
    } 

Insegnanti per la scuola

Richiesta URL Microsoft

~/ws/v1/school/{id}/staff?pagesize=100&page=1&expansions=emails,school_affiliations

Risposta di PowerSchool

    { 
     "staffs": { 
     "@expansions": "addresses, emails, phones, school_affiliations, school_counselors, 
                    teacher_global_id, staff_global_id", 
     "staff": [ 
      { 
        "id": , 
        "local_id": , 
        "teacher_username": "", 
        "name": { 
          "first_name": "", 
          "last_name": "" 
        }, 
        "emails": { 
          "work_email": "" 
        }, 
        "school_affiliations": { 
          "school_affiliation": { 
            "school_id": , 
            "type": , 
            "status":  
          } 
        }, 
        "users_dcid":  
      } 
     }
    }

Assicurarsi che gli endpoint REST siano accessibili a Internet

SDS (versione classica) deve essere in grado di raggiungere il server PowerSchool. Per assicurarsi che il server sia accessibile, aprire le porte 80 e 443 da Internet al server PowerSchool.

Per verificare che gli endpoint siano impostati correttamente, verificare che sia possibile aprire le pagine del sito Web del server PowerSchool da Internet. Ad esempio, nel browser passare a https://PowerSchool.com/public/. Se non funziona, contattare il supporto di PowerSchool.

Informazioni sugli avvisi di distribuzione di Microsoft Entra Connect

Se si configura SDS (versione classica) per un tenant, sincronizzato da Active Directory locale tramite Microsoft Entra Connect, è possibile notare un aumento del numero di disconnettitori visualizzato nel client errato. Ciò è il risultato dell'impossibilità per il gruppo di Microsoft 365 di eseguire la sincronizzazione con Microsoft Entra Connect Metaverse e active directory locale. Questi avvisi non hanno alcun impatto negativo sulla distribuzione corrente di Microsoft Entra Connect e forniscono solo una nota informativa sull'errore di sincronizzazione risultante. Questi avvisi dovrebbero essere previsti in Microsoft Entra Connect dopo l'abilitazione della sincronizzazione in SDS (versione classica). Viene creato un gruppo di Microsoft 365 per ogni classe sincronizzata tramite SDS (versione classica).

Sincronizzare i dati SIS usando il metodo di sincronizzazione dell'API PowerSchool

Dopo aver installato il plug-in e configurato l'accesso, creare un profilo di sincronizzazione in SDS (versione classica) per sincronizzare le informazioni.

Accesso SDS e accesso alla prima volta

Per accedere al portale di Amministrazione SDS avviare un Web browser, passare a sds.microsoft.com e quindi accedere usando l'account microsoft 365 Global Amministrazione.

Creare un profilo di sincronizzazione e sincronizzare i dati SIS

1. Dopo aver eseguito l'accesso, selezionare +Aggiungi profilo nel riquadro di spostamento a sinistra per creare un profilo di sincronizzazione.

   

2. Nella pagina Scegli tipo di connessione scegliere l'API PowerSchool e quindi scegliere il provider di integrazione SIS dal menu a discesa "Scegli il provider". Al termine, selezionare Avvia.

   

   • Assegnare un nome a questo profilo : immettere un nome per il profilo di sincronizzazione. Questo nome viene usato per identificare il profilo di sincronizzazione nel dashboard SDS (classico) e non può essere modificato al termine dell'installazione del profilo.
   • Scegliere il metodo di sincronizzazione : scegliere tra i metodi di sincronizzazione visualizzati. Se si esegue la sincronizzazione con l'API PowerSchool, selezionare la casella Connetti tramite un'API e quindi selezionare l'opzione API PowerSchool.

3. Nella pagina Opzioni di sincronizzazione selezionare l'opzione appropriata per creare nuovi utenti o sincronizzare gli utenti esistenti. Completare quindi le selezioni nella pagina in base alle esigenze.

   Nota

   Se è in esecuzione con l'opzione per la creazione di nuovi utenti e si vuole adottare il file CSV V2.1, è stato rilasciato uno strumento che consente di prepararsi a supportare il formato CSV V2.1 come parte della transizione per il ritorno all'istituto di istruzione. Vedere aggiornare gli ID di ancoraggio prima di creare gli utenti.

   

   • Utenti esistenti : selezionare questa opzione se sono già stati creati account utente all'interno dell'abbonamento a Microsoft 365 per ognuno degli studenti e degli insegnanti contenuti in PowerSchool.
   • Nuovi utenti : selezionare questa opzione se si vuole che SDS (versione classica) crei account utente per ognuno degli studenti e degli insegnanti contenuti in PowerSchool.

   Nota

   Se uno studente o un insegnante ha un nome utente all'interno di PowerSchool, SDS (classico) tenterà di usarlo per generare un account. Se tale nome utente non è disponibile, ne creerà uno nel formato seguente: s-<firstName>.<lastName>.<SIS ID>@<selectedDomain>

   • URL di accesso Web : questo è l'URL di base per il sis PowerSchool, accessibile da Internet.
   • ID client : id client registrato nella sezione Installare il plug-in API REST per PowerSchool di questo articolo.
   • Segreto client : si tratta del segreto client registrato nella sezione Installare il plug-in API REST per PowerSchool di questo articolo.
   • Selezionare le scuole da sincronizzare : questa opzione consente di selezionare l'istituto di istruzione da sincronizzare da PowerSchool.
   • Proprietà dell'istituto di istruzione: selezionare gli attributi dell'istituto di istruzione da includere.
   • Proprietà sezione : selezionare gli attributi dell'istituto di istruzione da includere.
   • Filtrare le proprietà inattive : se si seleziona questa casella verranno sincronizzati solo i record attivi.
   • Opzione di creazione team : se si seleziona questa casella, SDS crea sia il gruppo di Microsoft 365 che il team di classe per ogni classe sincronizzata. Se si lascia deselezionata la casella, SDS creerà solo il Gruppi di Microsoft 365.
   • Sostituisci caratteri non supportati : se si seleziona questa casella, i caratteri non supportati verranno sostituiti automaticamente con quelli supportati.
   • Opzione di sincronizzazione per Nome visualizzato gruppo di sezioni: la selezione di questa casella consentirà agli insegnanti di controllare il nome visualizzato della sezione dopo la prima sincronizzazione e impedirà a SDS di sovrascrivere le modifiche di Section DisplayName apportate dagli insegnanti.
   • Ritardare l'accesso degli studenti : l'abilitazione di questa opzione consente di impostare una data futura per consentire agli studenti di visualizzare le classi. Disabilitare questa opzione per consentire agli studenti di visualizzare immediatamente le classi.
   • Quando interrompere la sincronizzazione del profilo? - In genere si vuole eseguire questa operazione alla fine dell'anno scolastico. Dopo aver interrotto la sincronizzazione di questo profilo, è possibile ritirare le classi associate a questo profilo.

   Nota

   Al momento, il tenant singolo con formati misti (ad esempio con profili di sincronizzazione V1 e V2 in esecuzione e entrambi impostati su "Sincronizza in Insights") non funzionerà.

4. Nella pagina Opzioni docente selezionare le opzioni di corrispondenza delle identità appropriate, verificare che le proprietà dell'insegnante siano selezionate e quindi selezionare Avanti.

   

   • Chiave primaria (directory di destinazione): questo è l'attributo utente in Microsoft Entra ID usato per la corrispondenza delle identità SDS. Guardare il video sulla corrispondenza delle identità per altre informazioni su come selezionare l'attributo della directory di destinazione appropriato e configurare correttamente le impostazioni di corrispondenza delle identità per l'insegnante.
   • Dominio (facoltativo): si tratta di un valore di dominio facoltativo che è possibile aggiungere all'attributo della directory di origine selezionato per completare la corrispondenza di identità dell'insegnante. Se è necessario corrispondere a un attributo UserPrincipalName o Mail, è necessario includere un dominio nella stringa. L'attributo di origine deve includere già il dominio oppure è possibile aggiungere il dominio appropriato all'attributo di origine usando il menu a discesa.
   • Chiave primaria (directory di origine): questo è l'attributo Teacher in PowerSchool usato per la corrispondenza delle identità SDS. Guardare il video sulla corrispondenza delle identità per altre informazioni su come selezionare l'attributo della directory di origine appropriato e configurare correttamente le impostazioni di corrispondenza delle identità per l'insegnante.

5. Nella pagina Opzioni studente selezionare le opzioni di corrispondenza delle identità appropriate, verificare che le proprietà degli studenti siano selezionate e quindi selezionare Avanti.

   SDS controlla per assicurarsi di selezionare attributi e opzioni nel formato corretto. Se ad esempio si corrisponde a un userPrincipalName, è necessario selezionare un attributo di directory di origine, nel formato userPrincipalName (prefix@domain.com) oppure è necessario scegliere di accodare un dominio all'attributo della directory di origine per garantire la formattazione corretta. Se le selezioni non sono nel formato appropriato per completare una corrispondenza, verrà visualizzato un errore rosso nella pagina.

   

   • Chiave primaria (directory di origine): attributo studente in PowerSchool usato per la corrispondenza delle identità SDS. Guardare il video sulla corrispondenza delle identità per altre informazioni su come selezionare l'attributo della directory di origine appropriato e configurare correttamente le impostazioni di corrispondenza delle identità per l'insegnante.
   • Dominio (facoltativo): si tratta di un valore di dominio facoltativo che è possibile aggiungere all'attributo della directory di origine selezionato per completare la corrispondenza dell'identità degli studenti. Se è necessario corrispondere a un attributo UserPrincipalName o Mail, è necessario includere un dominio nella stringa. L'attributo di origine deve includere già il dominio oppure è possibile aggiungere il dominio appropriato all'attributo di origine usando il menu a discesa.
   • Chiave primaria (directory di destinazione): questo è l'attributo utente in Microsoft Entra ID usato per la corrispondenza delle identità SDS. Guardare il video sulla corrispondenza delle identità per altre informazioni su come selezionare l'attributo della directory di destinazione appropriato e configurare correttamente le impostazioni di corrispondenza delle identità per lo studente.

6. Nella pagina Verifica verificare di aver effettuato le selezioni appropriate. Se soddisfatto, selezionare Crea profilo.

   

Stato filtrato dell'API SIS powerschool

• Studenti e iscrizioni: SDS sincronizza alcuni studenti in base all'associazione e allo stato dell'istituto di istruzione.

  • Sincronizzati
    • Preregistrato
    • Attivazione
  • Non sincronizzato
    • Laureato
    • Eliminato
    • Trasferito in uscita

• Insegnanti: SDS sincronizza alcuni insegnanti in base all'associazione scolastica e al tipo di personale.

  • Sincronizzati
    • Insegnante
    • Sostituto
  • Non sincronizzato
    • Personale per il pranzo
    • Personale
    • Non assegnato

• Classi e scuole- SDS sincronizza tutto entro l'anno scolastico selezionato.

  

Video: Distribuzione dell'API PowerSchool

Video: Come trovare la corrispondenza tra gli attributi di origine e di destinazione per la sincronizzazione

Per vari esempi di esito positivo e negativo della logica di corrispondenza per la sincronizzazione, watch il video di corrispondenza delle identità: