Conseils d’intégration pour les fournisseurs d’API OneRoster avec School Data Sync (SDS)

Introduction

Synchronisation des données scolaires Microsoft (SDS) peut synchroniser les informations d’identité et de liste de n’importe quel système qui implémente la norme API OneRoster 1EdTech (Interfaces de programmation d’application) dans un flux de données entrant. Ce document est destiné à aider tous les nouveaux fournisseurs d’API OneRoster à s’intégrer correctement à SDS. Les clients peuvent se connecter directement à leur fournisseur à l’aide des API OneRoster 1.1 basées sur REST. Le processus d’intégration suivant définit les étapes requises par le fournisseur d’API avant qu’elles puissent être ajoutées pour que les locataires puissent sélectionner et utiliser dans SDS.

À propos de SDS

• Si vous souhaitez en savoir plus sur SDS, accédez au site du produit SDS.

• Pour obtenir des informations techniques sur SDS, notamment des vidéos de déploiement et des conseils d’administration, accédez au site de documentation SDS.

• Pour plus d’informations sur l’expérience client pour connecter des données avec l’API OneRoster, consultez Connecter des données avec l’API OneRoster.

Vue d’ensemble

1. Remplissez le formulaire sur le formulaire d’inscription du partenaire SDS.

   1. Indiquez que vous souhaitez l’aide sur l’intégration de La synchronisation des données scolaires sur le formulaire.

   2. L’inscription est nécessaire pour accéder au formulaire . Pour plus d’informations, visitez le site Microsoft Partner Network . Vous devez envoyer un formulaire distinct pour accéder aux ressources de développement SDS et Office.

2. Implémentez les points de terminaison de l’API OneRoster requis par SDS.

   SDS utilise un filtre sur la propriété dateLastModified pour le traitement de synchronisation différentielle/de synchronisation incrémentielle et est requis pour l’intégration à SDS.

3. Vérifiez que SDS fonctionne avec vos points de terminaison d’API OneRoster.

   1. Évaluez vos API à l’aide de la collection Postman.

   2. Testez avec l’ingénierie SDS sur un environnement de bac à sable.

   3. Configurez SDS pour valider la solution E2E.

4. Pilotez la solution avec deux clients de production.

5. Rendez votre connecteur généralement disponible dans SDS pour tous les locataires Office 365 EDU.

Prise en main

• Si vous venez de développer les API OneRoster, suivez la spécification de l’API OneRoster v1.1 pour la liste de base.

• Nous suggérons la certification en tant que fournisseur avec 1EdTech, mais ne l’exigez pas. 

• Pour plus d’informations sur la liste par défaut des valeurs prises en charge par SDS, consultez Liste de valeurs par défaut.

Points de terminaison d’API requis pour SDS

Points de terminaison d’API facultatifs pour SDS

Relations de contact utilisateur étudiant facultatives

La relation de contact étudiant peut être spécifiée pour les utilisateurs étudiants afin d’améliorer les expériences des enseignants pour la communication avec les parents et tuteurs des étudiants. Les contacts sont davantage d’utilisateurs fournis avec le point de terminaison /users et l’association à un étudiant se trouvent dans l’enregistrement utilisateur de l’étudiant sous « agents ».

• Pour plus d’informations, sur les rôles de relation de contact étudiant pris en charge par SDS, consultez Liste de valeurs par défaut : Rôles de relation de contact.
• familyName, givenName et email sont requis pour les utilisateurs qui ont des rôles de contact/tuteur.
• Le téléphone et les sms doivent être inclus dans E.164 et +. (Exemple : +1234567890).
• Si des données inversées sont fournies, d’un enregistrement tuteur de relation de contact à l’étudiant dans le champ « agents » des utilisateurs de contact, ces enregistrements sont filtrés.

Indicateurs démographiques utilisateur facultatifs

Les indicateurs utilisateur peuvent être spécifiés pour permettre aux utilisateurs étudiants d’indiquer leur participation à un programme ou à une cohorte. Les indicateurs utilisateur sont inclus (lorsqu’ils sont true pour l’utilisateur), ou non inclus si cela n’est pas applicable.

Les indicateurs sont spécifiés en tant qu’extension de métadonnées pour l’utilisateur, dans un champ de métadonnées. L’approche suit une clé|Paire valeur, avec la clé nommée microsoft.userFlags, et doit être mise en forme en tant que liste délimitée par des virgules. Les indicateurs utilisateur peuvent apparaître dans n’importe quel ordre et ne respectent pas la casse.

Pour plus d’informations, dans la liste par défaut des valeurs d’indicateur utilisateur prises en charge par SDS, consultez Liste de valeurs par défaut : Indicateurs utilisateur.

Exemple :

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

Règles de validation et de correspondance des données

Pour plus d’informations sur les règles de correspondance et de validation des données, consultez Règles et descriptions de validation.

Notes et conseils utiles

• Les points de terminaison viennent toujours après l’URL https : {server_URL}/ims/oneroster/v1p1.
• Tous les points de terminaison doivent prendre en charge la pagination, c’est-à-dire les paramètres de limite et de décalage (par exemple, limit=10&offset=5000).
• Les points de terminaison ont des exigences en matière de prise en charge des paramètres de filtre pour autoriser le filtrage par status ou pour activer la synchronisation delta.
• Les clients savent comment activer l’option « Est actif » ou comment autoriser uniquement la disponibilité des données actives pour la connexion qui doit être utilisée par School Data Sync. Cela garantit que seules les données actives de l’année scolaire et de la session actives sont fournies au fur et à mesure que l’année scolaire progresse.
• Pour empêcher l’inclusion de certaines écoles dans les données fournies du SIS vers SDS, les clients savent comment configurer les écoles incluses pour la connexion/les informations d’identification utilisées pour lier SDS à leur SIS.
• SDS applique un filtre sur la propriété dateLastModified pour le traitement de synchronisation delta/synchronisation incrémentielle et est requis pour l’intégration à SDS.
• Les fournisseurs doivent choisir d’implémenter le schéma d’authentification OAuth1(a) ou OAuth 2.0 (octroi d’informations d’identification du client), OAuth 2.0 préféré.
• Pendant le développement, vous pouvez vérifier vos points de terminaison avec notre collection Postman.
• Si le protocole d’authentification pris en charge est « OAuth 2 » - type d’octroi des informations d’identification du client, SDS envoie les informations d’identification dans l’en-tête « Authorization ». SDS ne prend pas en charge l’envoi des informations d’identification dans le corps de la demande.

Test de vos API OneRoster

Utilisation de la collection Postman

Postman est un outil bien connu pour exécuter et gérer des API REST. Nous avons créé la collection Postman de l’API OneRoster pour appeler et tester les API OneRoster requises par SDS. L’exécution de la collection appelle toutes les API requises par SDS et exécute des tests simples sur les données retournées.

Tester avec l’ingénierie SDS sur un environnement de bac à sable

Créez un environnement de bac à sable pour vos API OneRoster et partagez les informations d’identification avec votre ingénieur SDS désigné. Ensemble, nous exécutons un ensemble plus approfondi de tests pour garantir la réussite de l’intégration.

Configurer pour valider la solution

Lorsque tous les tests ont réussi, le nom de votre système est ajouté à la liste des fournisseurs OneRoster dans SDS. Toutefois, à l’heure actuelle, il n’est visible que pour les locataires testés pour les profils de fournisseurs indiqués comme étant en mode « InPilot » (non disponible publiquement). Ensuite, configurez SDS pour connecter des données avec l’API OneRoster dans votre locataire Microsoft 365 de test pour synchroniser les données de vos points de terminaison OneRoster de bac à sable et garantir que les exécutions se terminent sans erreur. Si vous voyez des erreurs ou des avertissements et que vous avez besoin d’aide après votre auto-investigation, contactez votre ingénieur SDS désigné.

Pilote client

Une fois les tests terminés, il est temps de commencer à tester la solution avec les clients. Le nom de votre système est visible dans la liste des fournisseurs OneRoster® dans SDS pour ceux qui sont « testés » pour voir également les fournisseurs qui sont en mode « InPilot », acceptant de piloter l’intégration. L’équipe SDS et l’équipe du fournisseur OneRoster collaborent pour identifier les clients pilotes appropriés et planifier le déploiement de SDS. Nous collaborons étroitement avec les clients pour nous assurer que les exécutions de flux entrants sont réussies et valider les résultats ensemble. Tous les bogues finaux identifiés doivent être résolus avant de rendre la solution accessible publiquement à tous les clients Office 365 éducation.

Rendre public

Une fois que deux clients ont réussi leurs déploiements pilotes, le système partenaire est disponible dans SDS en tant que système source de fournisseur OneRoster certifié. SDS affiche le nom du fournisseur aux locataires lorsqu’ils définissent leur configuration de données de connexion à l’aide de l’API OneRoster. L’équipe SDS documente le système partenaire sur notre page vue d’ensemble du fournisseur d’API OneRoster dans nos documents en ligne SDS.

L’équipe SDS a besoin des éléments suivants :

• Version minimale du logiciel
• Configuration requise
• Comment obtenir l’ID client, la clé secrète client et les URL
• Toute autre instruction spécifique
• Personne à contacter pour obtenir de l’aide

L’équipe SDS peut se coordonner avec votre équipe pour promouvoir l’intégration plus largement par le biais de différents canaux marketing.