Mappage de champs personnalisé du fichier plat d'instantané

Mappage de champ

Le système d'informations pour les étudiants Framework permet de personnaliser les données entrantes avant qu'elles ne soient ajoutées à Blackboard, enregistrement par enregistrement. Cela est utile lorsque les données de votre système d'informations pour les étudiants ne sont pas conformes à vos exigences en matière de données Blackboard et ne peuvent pas être modifiées dans le système d'informations pour les étudiants parce qu'elles sont prohibitives ou que les informations que les données représentent sont utilisées par d'autres systèmes. Ce document traite de l'utilisation de l'option Mappage de champs, en particulier l'utilisation de l'option de mappage de champs de script personnalisé.

Cette capacité de personnalisation des données entrantes est appelée Mappage de champ. Vous pouvez y accéder dans l'interface utilisateur sous le menu Configuration avancée de l'intégration.

L'écran Configuration avancée fournit la liste des objets pris en charge pour cet objet dans Blackboard. Ces alignements sur le type d'intégration varient d'un type d'intégration à l'autre.

Lorsque vous sélectionnez Mappage de champ sur un objet Learn associé au type d'intégration, dans ce cas Cours, vous êtes redirigé vers la page Mappage de champ correspondant à l'intégration.

Outre des informations utiles concernant le champ (par ex. s'il est requis pour l'insertion ou doit être unique), vous pouvez également sélectionner plusieurs paramètres qui contrôlent la façon dont les données entrantes sont gérées par l'intégration, ainsi que l'éventuel mappage des objets entrants.

Scripts personnalisés et mappage de champs

Vous pouvez choisir d'utiliser un autre champ entrant pour le champ pour lequel vous souhaitez définir un mappage. Par exemple : supposons que l'identifiant de cours entrant ne soit pas adapté à votre utilisation dans Blackboard, vous pourriez le mapper à la clé externe du cours à la place. Étant donné que ce didacticiel traite de l'utilisation d'un script personnalisé pour effectuer le mappage, vous devez sélectionner « Utiliser un script personnalisé » dans la liste déroulante « Champ source ».

Les scripts personnalisés sont basés sur JavaScript. Toutes les données entrantes sont mappées à un modèle d'objet interne qui offre la possibilité d'accéder à chaque élément de données, et d'utiliser ou de manipuler ses données ultérieurement à l'aide d'un JavaScript personnalisé.

Utilisez des comparateurs d'entiers dans les instructions de commutation JavaScript. Si vous devez utiliser des chaînes ou des caractères comme comparateurs, utilisez des instructions if/else plutôt que des instructions switch.

Deux excellentes références JavaScript sont fournies par le Mozilla Developer Network https://developer.mozilla.org/en-US/...ript/Reference et le World Wide Web Consortium (W3C) http://www.w3schools.com/jsref/.

Sélectionner « Utiliser un script personnalisé » affiche une zone de texte pour saisir votre code javascript.

C'est dans cette zone de texte que vous entrerez votre script personnalisé pour modifier les données entrantes.

Documentation intégrée à Blackboard

La documentation concernant les scripts de mappage de champs personnalisés se trouve sur la page d'exemples de documents liée à la page d'intégration du système d'information pour étudiants de niveau supérieur du panneau d'administration de Blackboard.

La page Exemples de documents contient des liens vers plusieurs références relatives au cadre d'intégration SIS couvrant tous les types d'intégration. Les deux documents intéressants dans le contexte du type d'intégration Snapshot Flat File et du mappage de champs personnalisé sont liés respectivement par Data Dictionary : Snapshot Flat File Integration et Custom Field Mapping Script Examples.

Scripts personnalisés

L'accès au modèle d'objet de chaque type d'intégration est différent et repose sur la structure de données sous-jacente de la spécification de données du type d'intégration. En comprenant la spécification des données d'intégration, vous pouvez déduire un modèle d'accès à tous les objets de l'intégration.

Dans le cas du fichier plat d'instantané, ce modèle est basé sur un objet racine de « data », nous pouvons donc déduire le modèle suivant :

data.getValue(<FlatFileDataObject>);

où <FlatFileDataObject> est remplacé par le nom de l'élément d'en-tête du flux de données.

Par exemple :

data.getValue("firstname");

data.getValue("lastname");

data.getValue("course_name");

En outre, lorsque le flux de données prend un « Y » ou un « N », vous devez le remplacer conditionnellement comme résultat du script par les valeurs booléennes true ou false respectivement. Par exemple :

var avail_ind = false;

if (data.getValue("available_ind").toUpperCase() == 'Y') {

avail_ind=true;

code de disponibilité ;

Ou, si on l'écrit à l'aide d'une instruction utilisant un opérateur ternaire :

état ? exécuter si la condition est vraie : exécuter si la condition est fausse  :

Par exemple :

data.getValue("available_ind").toUpperCase( )=='Y' ? avail_ind = true : avail_ind = false;

code de disponibilité ;

ce qui précède peut être réduit à une simple instruction ternaire, car il s'agit de la valeur finale de l'expression sur la dernière ligne du script qui est renvoyée en tant que point de données enregistré dans Blackboard.

Nous pouvons donc utiliser :

data.getValue("available_ind").toUpperCase() == 'Y' ? avail_ind = true : avail_ind = false;

et obtenir le même résultat.

Étant donné que les scripts personnalisés sont traités pour chaque enregistrement, les performances d'intégration peuvent être affectées si des scripts de calculs intensifs (tels que le chiffrement) sont exécutés. Notez également que l'accès aux données externes n'est pas pris en charge : vous ne pouvez effectuer des opérations que sur des données de flux existants ou des données dérivées de calculs.

Scripts de débogage

Le débogage de vos scripts est relativement facile, car les erreurs ou les problèmes de données que vous pouvez rencontrer sont consignés.

Par exemple :

Compte tenu du développement d'un script personnalisé sur le champ « Available » (disponible) :

data.getValue("available_ind");

peut s'exécuter correctement, mais si la valeur n'est pas transmise dans le flux de données, le script génère l'entrée suivante dans le journal :

Valeur nulle renvoyée pour l'attribut non nullable : IsAvailable.

Données non valides pour l'attribut : isAvailable. Valeur : null. En utilisant la valeur par défaut de Blackboard.

Tandis que (à supposer que available_ind st spécifié dans le flux) :

data.getValue("available_ind");

peut s'exécuter correctement, mais générer l'entrée suivante dans le journal :

Type de valeur non valide pour l'attribut : isAvailable. Valeur : y

Données non valides pour l'attribut : isAvailable. Valeur : Y . En utilisant la valeur par défaut de Blackboard.

c'est parce que nous devons modifier conditionnellement les données entrantes à la valeur booléenne attendue - dans ce cas «  TRUE  », afin que nous puissions modifier le script comme suit :

data.getValue("available_ind") == 'y'?true:false;

Mais pour plus de sécurité, nous voulons capturer des comparaisons en majuscules et minuscules, nous modifions donc le script comme suit :

data.getValue("available_ind").toUpper() == 'Y' ? true : false;

Cela se traduira par une erreur de script réelle et une impression dans le journal :

Erreur lors de l'exécution du script pour l'attribut : isAvailable.

blackboard.platform.script.ScriptingException: javax.script.ScriptException: sun.org.mozilla.javascript.internal.EcmaError: ReferenceError: "toUpper" is not defined. (<Unknown Source>#2) in <Unknown Source> at line number 2

C'est parce que JavaScript n'a pas toUpper (), mais qu'il a toUpperCase (), donc modifier le script...

data.getValue("available_ind").toUpperCase() =='Y' ? true : false;

Et il s'exécutera alors avec succès.

Scripts d'assistance : connexion à des scripts personnalisés

Blackboard fournit des scripts d'assistance qui fournissent des fonctionnalités communes telles que la journalisation de vos scripts. L'ajout des éléments suivants à vos scripts permettra d'inclure la sortie dans les journaux d'intégration :

helper.logError(msg)

helper.logWarning(msg)

helper.logInfo(msg)

helper.logDebug(msg)

La sortie des méthodes helper.log* sera visible dans les journaux en fonction de la configuration d'intégration pour les niveaux de journalisation.

Les scripts d'assistance supplémentaires disponibles (comme décrit sur la page Exemples de scripts de mappage de champs personnalisés liée à la page Exemples de documents) sont les suivants :

Poursuivant notre exemple de script, nous ajouterons un message de journal d'informations pour indiquer que la valeur utilisée dans Blackboard est dérivée d'un script personnalisé, de l'objet de données de base référencé pour les données insérées et des valeurs calculées qui ont été utilisées. Nous ajouterons également un message de journal indiquant une condition d'erreur basée sur l'absence de script valide.

En reprenant le script IsAvailable ci-dessus, supposons que le paramètre AVAILABLE_IND n'est pas défini de manière cohérente dans les flux de données des cours, ce qui signifie qu'il n'est pas toujours présent dans le flux de données, et que vous souhaitez le définir sur true lorsqu'une valeur pour AVAILABLE_IND n'est pas présente ou l'évaluer de manière appropriée ? Le script devient maintenant :

var outInd = false;

var inInd = data.getValue("available_ind")

if (inInd == "") {

helper.logInfo("INCOMING AVAILABLE_IND UNDEFINED for "+data.getValue("course_id")+": setting isAvailable to true");

outInd=true;

} else {

data.getValue("available_ind").toUpperCase()=='Y'?outInd=true:outInd=false;

}

helper.logInfo("OUTGOING AVAILABLE_IND: ["+outInd+"]");

outInd;

Le journal affiche maintenant :

31 mai 2013 16:03:56 - Cours [créer/mettre à jour, testCourse1]

INCOMING AVAILABLE_IND UNDEFINED for TEST_COURSE_1: setting isAvailable to true

OUTGOING AVAILABLE_IND: [true]

Le cours « TestCourse1 » a été traité avec succès.

testCourse1|TEST_COURSE_1|Test Course 1|

...

entrées de journal restantes

...

Cartographie des champs réussie.

Exemples

Nom du cours : Ajouter un trimestre et une année

Cas d'utilisation

Il est souhaitable que l'affichage des cours contienne la période de cours et l'année où le cours est proposé. Actuellement, les données fournies par le SIS n'ajoutent pas ces informations au course_name. Les cours sont affichés en utilisant le nom du cours. Par exemple :

Condition préalable

Le SIS fournit la période de cours et l'année dans le cadre de la chaîne de course_id ainsi que le champ course_name obligatoire.

Par exemple :

external_course_key|course_id|course_name|available_ind

Artist.202.01|36202010114|Histoire de l'art 202 : Architecture de la Renaissance|Y

Dans l’exemple ci-dessus, le course_id est composé de :

le département : 36

le cours : 202

la section : 01

mois du trimestre : 01

l'année : 14

Exigences

1. Les périodes sont déterminées par le mois désigné. Par exemple :

01 = Hiver

04 = Printemps

06 = Été

09 = Automne

2. Ajoutez la période de cours et l'année dérivées de la programmation au nom du cours, en les séparant par des espaces et entre parenthèses « () ». Par exemple :

Histoire de l'art 202 : Architecture de la Renaissance (hiver 2014)

3. Ignorez les informations ajoutées si la période appropriée n'est pas fournie.

État postérieur

1. Pour les cours pour lesquels course_id fournit des identificateurs de période de cours / d'année appropriés, la valeur (ANNÉE DE LA PÉRIODE) sera ajoutée aux données course_name avant de créer ou de mettre à jour l'enregistrement du cours dans Blackboard.

2. Le nom du cours ne sera pas modifié pour les cours dont les identifiants termes/années ne sont pas appropriés dans le course_id.

Scénario

Le nom du cours est fourni dans le champ course_name du flux de données système d'informations pour les étudiants et les informations terminologiques requises sont contenues dans le champ course_id des éléments du flux de données système d'informations pour les étudiants au format numérique. Pour répondre aux exigences, nous devons :

a) déterminer l'année, et

b) déterminer la période en la mappant sur une plage, puis formater correctement les données résultantes.

Pour ce faire, nous fournirons des fonctions javascript pour renvoyer le format souhaité pour l'affichage du nom du cours et correctement formater la sortie de ces fonctions.

a) Déterminez l'année.

Étant donné que le course_id contient une année à deux chiffres à la fin de la séquence de caractères, nous pouvons écrire une fonction pour extraire et renvoyer les deux derniers caractères :

function courseYear(crn) {

return crn.substring(9);

}

b) Déterminez le terme.

Le course_id nous fournit également les données nécessaires pour déterminer le terme et nous pouvons utiliser la fonction de sous-chaîne JavaScript pour extraire les données MM et les mapper à une plage de mois représentant un libellé de terme. Par exemple : 09=Automne, 01=Hiver, 04=Printemps, 06=Été

function getTerm(crn) {

var termCode=crn.substring(7, 9);

var term="";

if (termCode == "01") {

term="Winter";

} else if (termCode == "04") {

term="Spring";

} else if (termCode == "06") {

term="Summer";

} else if (termCode == "09") {

term="Fall";

} else {

term="";

}

return term;

}

function getYear(crn) {

return crn.substring(9);

}

Comme nous travaillons ici avec des entiers, nous pourrions écrire la fonction getTerm en utilisant une instruction switch au lieu de celle ci-dessus qui utilise if/else :

function getTerm(crn) {

var termCode = parseInt(crn.substring(7,9));

var term = "";

switch (termCode)

{

case 09: term ="Fall"; break;

case 01: term ="Winter"; break;

case 04: term ="Spring"; break;

case 06: term ="Summer"; break;

default: term ="";

}

return termString ;

}

Maintenant que nous avons des fonctions pour déterminer la période de cours et l'année, écrivons le script qui ajoute le course_name :

function getTerm(crn) {

var termCode=crn.substring(7, 9);

var term="";

if (termCode == "01") {

term="Winter";

} else if (termCode == "04") {

term="Spring";

} else if (termCode == "06") {

term="Summer";

} else if (termCode == "09") {

term="Fall";

} else {

term="";

}

return term;

}

function getYear(crn) {

return crn.substring(9);

}

var crn = data.getValue("course_id");

var year = getYear(crn);

var term = getTerm(crn);

var courseName = data.getValue("course_name");

var newCourseName = "";

if (term!="") {

newCourseName = courseName + " (" + term + " 20" + year + ")";

} else {

newCourseName = courseName;

}

helper.logInfo("INCOMING COURSE_NAME " + data.getValue("course_name"));

helper.logInfo("INCOMING COURSE CRN " + crn);

helper.logInfo("INCOMING COURSE YEAR " + year);

helper.logInfo("INCOMING COURSE TERM " + term);

helper.logInfo("INCOMING COURSE_NAME " + data.getValue("course_name"));

helper.logInfo("OUT NEW NAME " + newCourseName);

newCourseName;

En saisissant ce qui précède dans le mappage de champ de cours pour le nom du cours et, à l'aide de l'option de téléchargement de fichier d'intégration, en téléchargeant (stockant) manuellement l'exemple de flux de cours à partir de la condition préalable ci-dessus, vous verrez les données ci-dessous publiées dans les journaux de notre exemple de cours :

Et le nom du cours s'affiche désormais avec le terme et l'année tels qu'ils sont dérivés du course_id.

Mots de passe

Cas d'utilisation

Vous utilisez LDAP pour authentifier les utilisateurs Blackboard, mais Blackboard exige des mots de passe pour créer des comptes utilisateurs et votre système d'informations pour les étudiants ne fournit pas de mot de passe. Vous devez créer un mot de passe aléatoire par utilisateur.

Condition préalable

Le flux de données fournit les informations de base sur l'utilisateur qui peuvent être utilisées pour créer le mot de passe. Par exemple : prénom et nom

Exigences

Les mots de passe doivent être une combinaison de prénom+nom+nombre aléatoire.

Une plage doit pouvoir être spécifiée pour le randomisation.

État postérieur

Le mot de passe est créé pour l'utilisateur. Par exemple :

Pour l'utilisateur Jean Dupont, le mot de passe pourrait être jeandupont102464.

Exemples de données

external_person_key|user_id|passwd|firstname|lastname|email|system_role

testPerson1|aanderson_test|changeme|Alpha|Anderson||none

testPerson2|bvonbrown_test|changeme|Beta|Von Brown||none

testPerson3|ddavis_test|changeme|Delta|Davis!||none

testPerson4|ggardner_test|changeme|Gamma|G'Ardner||none

Scénario

fonction rand (min, max) {

var argc = arguments.length ;

si (argc === 0) {

minimum = 0 ;

maximum = 2147483647 ;

}

renvoie Math.floor (Math.random () * (max - min + 1)) + min ;

}

var password = « » ;

var regex = new RegExp(" ", 'g');

helper.logInfo("INCOMING PASSWORD: " + data.getValue("passwd"));

helper.logInfo("INCOMING FIRSTNAME: " + data.getValue("firstname"));

helper.logInfo("INCOMING LASTNAME: " + data.getValue("lastname"));

password = (data.getValue("firstname") + data.getValue("lastname") + rand() + rand()).toUpperCase();

mot de passe = password.replace (regex, «) ;

helper.logInfo("GENERATED PASSWORD: " + password);

mot de passe ;

En saisissant ce qui précède dans le mappage de champ Utilisateur pour le Mot de passe et en téléchargeant (stockant) manuellement l'exemple de flux Utilisateur (personne) à partir des exemples de données ci-dessus, vous verrez les données ci-dessous publiées dans les journaux :

Courriels

Cas d'utilisation

Votre système d'informations pour les étudiants ne stocke pas les comptes e-mail des étudiants ou les comptes e-mail personnels, mais pas ceux émis par votre établissement. Vous souhaitez que les e-mails de Blackboard soient les comptes de messagerie émis par l'établissement.

Condition préalable

Les données requises pour générer la partie locale de l'adresse e-mail souhaitée existent dans le flux de données SIS. Par exemple : prénom et nom

Exigences

Les comptes de messagerie émis par l'établissement suivent le modèle [email protected] où « -yy » représente l'année d'obtention du diplôme prévue pour l'étudiant. Ces éléments sont transmis dans le flux SIS dans les données suivantes :

FIRSTNAME : prénom de l'étudiant

MIDDLENAME : deuxième prénom de l'étudiant

LASTNAME : nom de l'étudiant

OTHERNAME : année de l'obtention du diplôme

La partie locale des adresses e-mail acceptables ne doit contenir que des caractères alphanumériques, « '-','_','.' » et des apostrophes. Par exemple : Gamma.G'[email protected]

État postérieur

Une adresse e-mail correctement formatée est générée et transmise à Blackboard.

Exemples de données

external_person_key|user_id|passwd|firstname|lastname|email|system_role

testPerson1|aanderson_test|changeme|Alpha|Anderson||none

testPerson2|bvonbrown_test|changeme|Beta|Von Brown||none

testPerson3|ddavis_test|changeme|Delta|Davis!||none

testPerson4|eedwards_test|changeme|E...nstitution.edu|none

testPerson5|ggardner_test|changeme|Gamma|G'Ardner||none

Scénario

var emailAddress = "";

var instDomain = "institution.edu";

function buildIt() {

var fname = data.getValue("firstname");

var lname = data.getValue("lastname");

var regex = new RegExp(" ", 'g');

emailAddress = fname +"."+lname+"@"+instDomain;

emailAddress=emailAddress.toLowerCase();

emailAddress = emailAddress.replace(regex, '');

}

function validateIt(eAddress) {

var emailRegEx = /^([a-zA-Z0-9_\.\-\'])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$/;

if (!emailRegEx.test(eAddress))

throw new Error("Email Validator Error: Cannot Validate Email Address");

}

emailAddress = data.getValue("email");

if (emailAddress == "" || emailAddress == null) {

buildIt();

} else if ( emailAddress.indexOf(instDomain) === -1) {

buildIt()

}

try {

validateIt(emailAddress);

} catch (err) {

helper.logError("INCOMING EMAIL ADDRESS: " + emailAddress);

helper.logError("INCOMING FIRSTNAME: " + data.getValue("firstname"));

helper.logError("INCOMING LASTNAME: " + data.getValue("lastname"));

helper.logError(err +" for User (" + data.getValue("user_id") +", Email (" + emailAddress + "). No Email Address Saved for this user. )");

emailAddress="";

}

helper.logInfo("emailAddress: " + emailAddress);

emailAddress;

En saisissant ce qui précède dans le mappage de champ Utilisateur pour le Mot de passe et en téléchargeant (stockant) manuellement l'exemple de flux Utilisateur (personne) à partir des exemples de données ci-dessus, vous verrez une erreur publiée dans les journaux.

En effet, les adresses e-mail ne peuvent pas contenir de points d'exclamation selon notre expression régulière.

Notez que l'utilisateur est toujours créé, car aucune adresse e-mail valide n'est requise pour la création ni pour la mise à jour d'un enregistrement d'utilisateur.

Remplacement de l'entrée pour Delta Davis :

testPerson4|ddavis_test|changeme|Delta|Davis!||none

par

testPerson4|ddavis_test|changeme|Delta|Davis||none

suppression du « ! » dans le champ du nom de famille de Delta et le téléchargement à nouveau du fichier supprime l'erreur et met à jour l'enregistrement de Delta avec la nouvelle adresse e-mail.

Ignorer un enregistrement ou un attribut en cas d'erreur

Helper fournit deux méthodes supplémentaires qui permettent un contrôle encore plus grand sur le traitement de vos scripts :

helper.skipAttribute() - ignore un attribut non critique qui semble avoir été défini de manière incorrecte

helper.skipRecord() - ignorer l’enregistrement entier et passer au suivant

Le script d'e-mail ci-dessus enregistre une erreur lorsque l'adresse e-mail ne peut pas être validée, mais continue à créer l'enregistrement malgré tout. Si nous ne voulions pas créer d'utilisateur sans adresse e-mail, mais plutôt enregistrer l'erreur de validation et passer à l'enregistrement suivant, nous ajouterions helper.skipRecord() dans un conditionnel basé sur emailAddress à la fin du script. Par exemple :

au lieu de fermer le script avec e-mailAddress= "" ; fermez-le avec :

(emailAddress=="") ? helper.skipRecord(): emailAddress;

Le script ignorera conditionnellement l'enregistrement en raison du contenu de la valeur emailAddress que nous avons définie comme une chaîne vide lorsque la validation a échoué.

Ajoutez la méthode Helper.skipRecord () au script et modifiez l'entrée pour Delta Davis comme suit :

testPerson4|ddavis_test|changeme|Delta|Davis||none

par

testPerson4|ddavis_test|changeme|Delta|Davis!||none

En téléchargeant (stockant) manuellement l'exemple révisé, avec un point d'exclamation, de flux utilisateur (personne), vous constaterez la publication de données dans les journaux.

Notez que l'erreur est consignée et que la fin du journal indique que l'enregistrement a été ignoré en raison du script de mappage et de l'attribut qui a renvoyé le résultat.

L'application conditionnelle de Helper.SkipAttribute () aura le même impact : le script traitera les données du flux et en fonction de la présence d'une condition comme ligne finale appelant Helper.skipAttribute (), l'intégration générera une erreur et ignorera l'enregistrement ou, si l'attribut n'est pas requis, la configuration de mappage prend le contrôle et gère l'attribut tel qu'il a été configuré.