L'un des principaux critères d'une intégration SIS réussie repose sur l'automatisation et la surveillance du flux des données envoyé à Learn par l'intégration. Deux nouvelles fonctionnalités facilitent ce processus :
- Les résultats de l'intégration des URL POST contiennent un code unique de traitement de l'ensemble de données. Par exemple :
Success: Feed File Uploaded. Use the reference code afc3d6e84df84f51944a06cccee8f59a to track these records in the logs.
- Une nouvelle URL d'état de l'ensemble de données a été ajoutée. Lorsqu'elle est contactée avec le code de traitement de l'ensemble de données, l'URL renvoie un bloc XML contenant des précisions sur l'état de l'ensemble de données en question. Notez que cet appel peut être effectué bien après l'application de l'opération POST au fichier de données initial.
https:// ... /webapps/bb-data-integration-flatfile-[YOUR ID]/endpoint/dataSetStatus/afc3d6e84df84f51944a06cccee8f59a
renvoie :
<dataSetStatus>
<completedCount>5</completedCount>
<dataIntegrationId type="blackboard.platform.dataintegration.DataIntegration">_123_1</dataIntegrationId>
<dataSetUid>afc3d6e84df84f51944a06cccee8f59a</dataSetUid>
<errorCount>0</errorCount>
<lastEntryDate>2013-03-20T10:45:48-05:00</lastEntryDate>
<queuedCount>0</queuedCount>
<startDate>2013-03-20T10:45:48-05:00</startDate>
<warningCount>0</warningCount>
</dataSetStatus>En savoir plus sur les identificateurs de base de données dans les déploiements SaaS
Ces ajouts facilitent le suivi par script des intégrations automatisées de fichier plat d'instantané.
Cette rubrique présente la procédure d'automatisation et de surveillance d'une intégration de fichier plat d'instantané. Les exemples fournis sont écrits pour une plate-forme UNIX ou Linux utilisant CRON pour l'automatisation et le langage de script shell UNIX BASH. Ces concepts peuvent toutefois être appliqués à n'importe quel langage capable d'effectuer des opérations POST/GET, d'analyser les chaînes de caractères et les dates, d'effectuer des requêtes dans la base de données et d'envoyer des e-mails. Ainsi les langages PERL, JAVA, PHP et Ruby sont adaptés au développement, tout comme les autres langages shell ou batch.
L'objectif est de fournir une implémentation de référence fonctionnelle pour le développement d'une intégration SIS surveillée et automatisée avec des fichiers plats d'instantané. Deux volets seront étudiés : l'automatisation et la surveillance. L'implémentation de référence est disponible via le lien disponible au bas de cette page.
L'inclusion de messages d'erreur consignés via l'implémentation de référence présentée n'est actuellement compatible qu'avec les systèmes auto-hébergés. Cette fonctionnalité est décrite dans le script et nécessite de supprimer les commentaires du code pour une utilisation dans des environnements auto-hébergés. Les clients Managed Hosting continueront à utiliser l'interface de journalisation de la structure SIS Learn pour accéder aux messages d'erreur. Une prochaine version de ce document fournira un moyen d'accès à ces messages de journalisation directement dans le script.
Use case (Cas d'utilisation) : automatisation du traitement des fichiers plats SIS
Le cas d'utilisation suivant sert de base à l'implémentation de référence et de référence personnelle.
Synthèse
Automatisez le traitement des données de fichier plat d'instantané générées par le système SIS et envoyez les rapports par e-mail aux administrateurs spécifiés. La solution doit régulièrement déterminer la présence de nouveaux fichiers de données, l'objet et la source des données, et présenter les données à Learn. Les fichiers traités doivent être placés dans un répertoire distinct à des fins d'archivage. La solution doit également permettre le traitement manuel des fichiers de données. Dans tous les cas, les e-mails d'état transmis en cas d'échec ou de réussite doivent être envoyés aux administrateurs. L'e-mail doit contenir les données disponibles concernant le processus et tous les messages d'erreur.
Acteurs
SIS, planificateur du système d'exploitation, Learn
Conditions préalables
Dans le répertoire spécifié, le système SIS génère et stocke les fichiers texte au format Fichier plat d'instantané pour les objets Learn, tels que les utilisateurs, les cours, les inscriptions et les affectations du personnel.
Description
- Le SIS fournit des fichiers plats d'instantané dans un répertoire de données spécifié par script.
- Le planificateur de système d'exploitation (CRON) démarre le script sis_snpshtFF_auto.
- Le script sis_snpshtFF_auto vérifie la présence de fichiers dans le répertoire de données.
- Le script sis_snpshtFF_auto détermine le type d'objet Learn de chaque fichier.
- Le script sis_snpshtFF_auto appelle le script sis_snpshtFF_manual et dans la hiérarchie d'objets : utilisateurs, cours, adhésions
- Le script sis_snpshtFF_manual utilise une opération POST pour envoyer les données à Learn et détermine l'état d'achèvement.
- En cas d'erreurs et s'il est configuré pour cela, le script sis_snpshtFF_manual recherche des messages d'erreur dans les journaux d'intégration.
- Le script sis_snpshtFF_manual rédige un e-mail contenant des informations d'état et l'envoie aux adresses e-mail configurées.
- Les étapes 5 à 8 sont répétées pour chaque fichier de données.
- Une fois qu'il a fini de traiter tous les fichiers de données, le script sis_snpshtFF_auto envoie un e-mail d'état aux adresses e-mail configurées.
Conditions postérieures
Les données fournies par les fichiers plats générés par SIS sont classées séquentiellement par objet de données ajouté à Learn. Les fichiers d'origine sont quant à eux archivés (l'horodatage de traitement est ajouté au nom de fichier d'origine). Les administrateurs configurés par script reçoivent des e-mails d'état par fichier traité et un e-mail d'état global couvrant l'ensemble de la tâche de traitement.
Solution
Mis à part la génération des fichiers de données par le système SIS, qui sort du champ d'application du présent document, le problème de l'automatisation comporte trois volets :
- Quand : déterminer quand exécuter le traitement des données fournies
- Quoi : déterminer les objets et sources de données que couvrent les données fournies
- Comment : traitement et surveillance des données en question
En utilisant le cas d'utilisation ci-dessus, nous pouvons construire un ensemble de scripts configurables qui peuvent déterminer si un fichier de données existe (si cette tâche doit faire quoi que ce soit) et si le type d'objet auquel les données s'appliquent, appeler un script de traitement avec les paramètres appropriés pour répondre aux objectifs d'intégration, traiter les données, et pour finir, archiver le fichier de données.
Les sections suivantes présentent ces trois volets. La mise en place de ces trois aspects permettra d'automatiser le transfert des données du SIS vers Learn via une intégration de fichier plat d'instantané.
Le script BASH a été largement commenté ; il ne sera donc pas proposé ici. Nous mettrons plutôt l'accent sur le flux global et les détails des traitements.
Comment : Utilisation des scripts sis_snpshtFF_auto.sh et sis_snpshtFF_manual
Sur la base du cas d'utilisation ci-dessus, le script BASH ci-dessous (sis_snpshtFF_auto.sh) effectue les opérations suivantes :
- Il vérifie si des fichiers se trouvent dans le répertoire spécifié.
- Il détermine le type d'objet et l'opération en fonction des informations d'en-tête du fichier.
- Il ordonne le traitement afin que les fichiers soient traités dans l'ordre approprié. Par exemple : utilisateurs, puis cours, puis adhésions.
- Il appelle un sous-script (sis_snpshtFF_manual.sh) pour le traitement, la surveillance et l'administration des notifications par e-mail relatives à l'état du traitement.
- Il archive le fichier de données à la fin du traitement.
- Il traite le fichier de données suivant, le cas échéant.
- Enfin, il envoie un rapport indiquant le résultat cumulé de l'appel au script d'automatisation.
Quoi : sis_snpshtFF_auto.sh
À un niveau élevé, le script sis_snpsht_auto charge les fichiers trouvés dans le répertoire de données configuré, analyse l'en-tête des données du fichier pour déterminer le type d'objet référencé et ajoute le fichier à la liste appropriée pour un traitement ultérieur. L'analyse de l'en-tête détermine le type d'objet auquel le fichier se réfère et, par conséquent, son ordre dans la file d'attente de traitement des instantanés. Ce tri autorise un seul point de stockage pour les fichiers plats générés par le SIS.
Une fois tous les fichiers analysés et regroupés dans des listes correspondant à leur type d'objet, ces listes sont traitées dans l'ordre logique Utilisateurs, Cours, puis Adhésions. Chaque fichier est transmis au script sis_snpshtFF_manual pour traitement, ce dernier pouvant également être exécuté à partir de la ligne de commande, avec les arguments appropriés pour chaque type d'objet. Le script sis_snpshtFF_manual prend les arguments entrants et utilise l'URL appropriée pour envoyer à l'aide d'une opération POST le fichier de données à Learn. Une fois l'envoi effectué, le script entre dans une boucle de surveillance, puis crée un rapport et l'envoie par e-mail à la liste configurée des destinataires. Le fichier est renvoyé au script sis_snpsht_auto, qui envoie le fichier suivant pour traitement. Ce processus est répété jusqu'à ce que tous les fichiers aient été traités. Une fois tous les fichiers traités, sis_snpshtFF_auto envoie un rapport final par e-mail à la liste des destinataires configurés.
Quand : Utilisation de CRON pour planifier des instantanés
Le but de l'automatisation est l'exécution du script sans intervention humaine. UNIX fournit cette capacité avec CRON, une application de planification intégrée. Un processus système, CRON, vérifie périodiquement le crontab système, un fichier système qui contient une liste de commandes et de paramètres d'exécution. Les entrées sont ensuite évaluées pour déterminer si elles doivent être exécutées immédiatement ou plus tard, comme indiqué dans l'entrée crontab.
La fréquence des tâches cron et les temps de traitement des opérations doivent être pris en compte dans le paramétrage des entrées crontab, car les opérations REFRESH peuvent être plus longues que les opérations STORE. Le traitement des données REFRESH par rapport aux données STORE peut être effectué via des entrées crontab distinctes et des répertoires de sources de données différents dans les arguments de script si vous utilisez le script fourni ci-dessous.
Expressions CRON pour entrées crontab
Format : CRON utilise un format très spécifique pour la planification des données. Il repose sur une liste de cinq champs de données obligatoires séparés par des espaces :
| Champ | Description | Valeur autorisée |
|---|---|---|
| MIN | Champ Minute | De 0 à 59 |
| HOUR | Champ Heure | De 0 à 23 |
| DOM | Jour du mois | 1-31 |
| MON | Champ du mois | 1-12 |
| DOW | Jour de la semaine | 0-6 |
| CMD | Commande | Toute commande à exécuter. |
Dans la pratique, ce format peut être appliqué de façon aussi simple ou complexe que vous le souhaitez.
Exemples :
une entrée crontab simple pourrait être d'exécuter une tâche toutes les heures :
0 * * * * /usr/local/blackboard/apps/snapshot/scripts/sis_snpshtFF_auto.sh
- 0 - Minute 0
- * - Toutes les heures
- * - Tous les jours
- * - Tous les mois
- * - Tous les jours de la semaine
ou une fois à minuit tous les jours :
0 0 * * * /usr/local/blackboard/apps/snapshot/scripts/sis_snpshtFF_auto.sh
- 0 - Minute 0
- 0 - Toutes les heures
- * - Tous les jours
- * - Tous les mois
- * - Tous les jours de la semaine
Exécutez une tâche deux fois par jour pendant la semaine de travail :
0 11,16 * * 1-5 /usr/local/blackboard/apps/snapshot/scripts/sis_snpshtFF_auto.sh
- 0 - Minute 0 (heure pile)
- 11,16 - 11 h et 16 h
- * - Tous les jours
- * - Tous les mois
- 1 à 5 jours - Du lundi au vendredi
ou toutes les deux heures du lundi au vendredi :
0 */2 * * Mon-Fri /usr/local/blackboard/apps/snapshot/scripts/sis_snpshtFF_auto.sh
- 0 - Minute 0 (heure pile)
- */2 - Toutes les heures paires 12, 2, 4, 6, 8, 10, 12, 14, etc. ou toutes les heures impaires.
- * - Tous les jours
- * - Tous les mois
- Lun-Ven : du lundi au vendredi
Vous pouvez également afficher la page de manuel de votre système via la ligne de commande en utilisant la commande $ man 5 crontab
Ajout d'un crontab
À l'aide des paramètres cron ci-dessus, nous pouvons ajouter une entrée crontab pour planifier l'exécution de l'instantané.
- Pour modifier votre fichier crontab racine, en tant qu'utilisateur root, tapez la commande suivante à l'invite de commande du shell UNIX/Linux :
$ crontab -e
Notez que -e vous renvoie à un éditeur vi.
- Pour exécuter le script de traitement automatisé des fichiers plats à minuit tous les jours, ajoutez ce qui suit à la liste des tâches :
root@dev$ crontab -e
- Saisissez i pour passer en mode édition, puis saisissez :
0 0 * * * /usr/local/blackboard/apps/snapshot/scripts/sis_snpshtFF_auto.sh
- Appuyez sur Échap pour sortir du mode édition.
- Saisissez :wq pour enregistrer votre modification et quitter l'éditeur.
Références
Les personnes suivantes ont soumis des idées, des contributions et des suggestions pour l'implémentation de la référence BASH :
Kelt Dockins a soumis son implémentation BASH pour l'analyse du contenu des fichiers plats d'instantané (désormais indisponible en ligne).
Ross Brown et Jerald Todd ont décelé certains des premiers problèmes exposés dans la première version de l'implémentation de référence.
Fichiers
Cette archive téléchargeable SIS_SnpshtFF_Bash_Scripts (zip) contient du code fonctionnel et commenté présentant les concepts abordés dans cette rubrique.
