Veldtoewijzing voor tekstbestanden zonder opmaak van Momentopname

Veldtoewijzing

Het Studentinformatiesysteem Framework ondersteunt het aanpassen van binnenkomende gegevens voordat deze per record aan Blackboard worden toegevoegd. Dit is handig wanneer de gegevens uit je Studentinformatiesysteem-systeem niet zijn afgestemd op de gegevensvereisten van Blackboard en niet kunnen worden gewijzigd in het Studentinformatiesysteem omdat het verboden is of omdat de informatie die de gegevens vertegenwoordigen door andere systemen wordt gebruikt. Dit document legt het gebruik van de optie 'Veldtoewijzing' uit, met name hoe je de optie Veldtoewijzing aangepast script kunt gebruiken.

Deze mogelijkheid om de inkomende gegevens aan te passen heet Veldtoewijzing en wordt geopend in de UI via het menu Geavanceerde configuratie van de integratie.

Het scherm Geavanceerde configuratie biedt een lijst van de objecten die voor dat object in Blackboard worden ondersteund. Deze worden afgestemd op het integratietype en verschillen per integratietype.

Wanneer je Veldtoewijzing selecteert op een Learn-object dat is gekoppeld aan het integratietype, in dit geval Cursussen, word je naar de pagina Veldtoewijzing voor de integratie geleid.

Naast nuttige informatie over het veld, zoals of het vereist is om in te voegen of dat het uniek moet zijn, kun je ook verschillende instellingen selecteren die bepalen hoe inkomende gegevens worden beheerd door de integratie en of je kiest voor toewijzing tussen inkomende objecten.

Aangepaste scripts en veldtoewijzing

In het veld dat je een veldtoewijzing wilt bieden, kun je een ander inkomend veld selecteren. Bijvoorbeeld: stel dat de binnenkomende cursus-ID niet geschikt is voor gebruik in Blackboard, dan kun je deze in plaats daarvan toewijzen aan de externe sleutel van de cursus. Aangezien deze tutorial gaat over het gebruiken van een aangepast script om de toewijzing uit te voeren, selecteer je 'Aangepast script gebruiken' in de keuzemogelijkheid ‘Bronveld’.

Aangepaste scripts zijn gebaseerd op JavaScript. Alle inkomende gegevens worden toegewezen aan een intern objectmodel dat toegang biedt tot elk gegevenselement voor de gegevens en vervolgens gebruik in of manipulatie met behulp van een aangepast JavaScript.

Gebruik vergelijkingsmiddelen met gehele getallen in JavaScript-switch-instructies. Als je tekenreeksen of tekens als comparators moet gebruiken, gebruik dan ‘if/else’-opdrachten in plaats van ‘switch’-opdrachten.

Twee uitstekende JavaScript-referenties worden geleverd door het Mozilla Developer Network https://developer.mozilla.org/en-US/...ript/Reference en het World Wide Web Consortium (W3C) http://www.w3schools.com/jsref/.

Als je 'Aangepast script gebruiken' selecteert, krijg je een tekstgebied om je JavaScript-code in te voeren.

In dit tekstgebied voer je een aangepast script in om de inkomende gegevens te bewerken.

Documentatie op het bord

Documentatie met betrekking tot scripts voor aangepaste veldtoewijzing is te vinden op de pagina Voorbeelddocumenten met een link vanaf de pagina Integraties van het Studentinformatiesysteem op het hoogste niveau in het configuratiescherm voor Blackboard-beheerders.

Met de koppeling Voorbeelddocumenten wordt een pagina geopend met verschillende koppelingen naar documenten van het SIS Integration Framework voor alle typen integratie. De twee documenten die van belang zijn in de context van het integratietype Snapshot Flat File en Custom Field Mapping zijn gekoppeld door Data Dictionary: Snapshot Flat File Integration en Custom Field Mapping Script Examples (Snapshot Flat File Integration) en Custom Field Mapping Scriptvoorbeelden.

Aangepaste scripts

De toegang tot het objectmodel van elk integratietype is verschillend en is gebaseerd op de onderliggende gegevensstructuur van de gegevensspecificatie van het integratietype. Aan de hand van de integratiegegevensspecificatie kun je een patroon afleiden voor toegang tot alle objecten van de integratie.

In het geval van Momentopname-bestand is dit patroon gebaseerd op een hoofdobject van 'data' zodat het volgende patroon kan worden afgeleid:

data.getValue(<FlatFileDataObject>);

waarbij <FlatFileDataObject> wordt vervangen door de naam van het headerelement uit de gegevensfeed.

Bijvoorbeeld:

data.getValue("voornaam");

data.getValue("achternaam");

data.getValue("course_name");

Als de gegevensfeed een 'Y' of 'N' heeft, moet u bovendien als scriptresultaat voorwaardelijk vervangen door respectievelijk de booleaanse waarden waar of onwaar. Bijvoorbeeld:

var avail_ind = false;

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

avail_ind=true;

avail_ind;

of een stelling schrijven met een ternaire operator:

voorwaarde ? Uitvoeren als voorwaarde waar: Uitvoeren als voorwaarde onwaar :

Bijvoorbeeld:

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

avail_ind;

het bovenstaande kan verder worden teruggebracht tot alleen de ternaire instructie, aangezien dit de uiteindelijke waarde is van de expressie op de laatste regel van het script die wordt geretourneerd als het gegevenspunt dat is opgeslagen in Blackboard.

Zodat we het volgende kunnen gebruiken:

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

en hetzelfde resultaat krijgen.

Bepaalde aangepaste scripts worden per record verwerkt voor integratie en prestaties kunnen beïnvloed worden als er computerintensieve scripts (zoals versleuteling) worden uitgevoerd. Denk eraan dat het openen van externe gegevens niet wordt ondersteund. Je kunt alleen bewerkingen uitvoeren op bestaande invoergegevens of op computergebaseerde gegevens.

Scripts voor foutopsporing

Foutopsporing van scripts is relatief eenvoudig omdat de fouten of gegevensproblemen die je mogelijk tegenkomt, in het logboek worden opgeslagen.

Bijvoorbeeld:

Gezien de ontwikkeling van een aangepast script op het veld 'Beschikbaar':

data.getValue("available_ind");

kan worden uitgevoerd, maar als de waarde niet wordt doorgegeven in de gegevensfeed, wordt door het script de volgende vermelding in het logboek gegenereerd:

Null-waarde die wordt geretourneerd voor het kenmerk dat niet kan worden geannuleerd: isAvailable.

Ongeldige gegevens voor het kenmerk: isAvailable. Waarde: null. Met behulp van de standaard Blackboard-waarde.

Waarbij als (ervan uitgaande dat available_ind in de feed wordt opgenomen):

data.getValue("available_ind");

uitgevoerd kan worden, maar geeft de volgende vermelding in het logboek:

Ongeldig waardetype voor kenmerk: isAvailable. Waarde: y

Ongeldige gegevens voor het kenmerk: isAvailable. Waarde: Y. Met behulp van de standaard Blackboard-waarde.

dat komt omdat we de binnenkomende gegevens voorwaardelijk moeten wijzigen naar de verwachte booleaanse waarde - in dit geval "TRUE", dus we kunnen het script veranderen in:

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

Maar voor de zekerheid willen we vergelijkingen tussen hoofdletters en kleine letters vastleggen, dus we passen het script aan:

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

Hierdoor treedt er een scriptfout op en wordt deze naar het logboek gevoerd:

Fout in de uitvoering van het script voor het kenmerk: 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

Dit komt omdat JavaScript geen toUpper() heeft, maar wel toUpperCase() dus het bewerken van het script...

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

wordt het script nu uitgevoerd.

Helper-scripts: Inloggen in aangepaste scripts

Blackboard biedt hulpscripts voor het bieden van algemene mogelijkheden, zoals het registreren van scripts. Als je de volgende opties toevoegt aan scripts, wordt de uitvoer opgenomen in de integratielogboeken:

helper.logError(msg)

helper.logWarning(msg)

helper.logInfo(msg)

helper.logDebug(msg)

De uitvoer van de methoden helper.log* wordt weergegeven in logboeken op basis van de integratieconfiguratie voor logboekregistratieniveaus.

Er zijn aanvullende hulpscripts beschikbaar (zoals beschreven op de pagina Voorbeelden van scripts voor aangepaste veldtoewijzing waarnaar wordt verwezen vanaf de pagina Voorbeelddocumenten):

Als we doorgaan met ons voorbeeldscript, voegen we een informatielogboekbericht toe om aan te geven dat de waarde die in Blackboard wordt gebruikt, is afgeleid van een aangepast script, het basisgegevensobject waarnaar wordt verwezen voor de ingevoegde gegevens en de berekende waarden die zijn gebruikt. We voegen ook een logboekbericht toe waarin een foutvoorwaarde wordt aangegeven omdat er geen geschikt script beschikbaar is

Als we het bovenstaande script opnieuw bekijken, laten we zeggen dat de AVAILABLE_IND inconsistent is ingesteld in cursusgegevensfeeds - wat betekent dat deze niet altijd aanwezig is in de gegevensfeed - en dat u deze op waar wilt instellen wanneer een waarde voor AVAILABLE_IND niet aanwezig is of op een andere manier op de juiste manier wilt evalueren? Het script wordt nu:

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;

Het logboek geeft nu het volgende weer:

31 mei 2013 16:03:56 - Cursus [maken/bijwerken, testCourse1]

INCOMING AVAILABLE_IND UNDEFINED for TEST_COURSE_1: setting isAvailable to true

OUTGOING AVAILABLE_IND: [true]

Cursus 'testCourse1' is succesvol verwerkt.

testCourse1|TEST_COURSE_1|Test Course 1|

...

Resterende logboekvermeldingen

...

Veldkartering succesvol.

Voorbeelden

Cursusnaam: Term en jaar toevoegen

Gebruik

Het is wenselijk dat de weergave van cursussen het semester en jaar bevat waarin de cursus wordt aangeboden. De gegevens die door het SIS worden verstrekt, voegen deze informatie momenteel niet toe aan de course_name. Cursussen worden weergegeven aan de hand van de cursusnaam. Bijvoorbeeld:

Voorwaarde

Het SIS bevat het semester en jaar als onderdeel van de tekenreeks course_id en bevat het vereiste veld course_name.

Bijvoorbeeld:

external_course_key|course_id|course_name|available_ind

ARTHIST.202.01|36202010114|Art History 202: Renaissance Architecture|Y

In het bovenstaande voorbeeld bestaat de course_id uit:

De afdeling: 36

De cursus: 202

De sectie: 01

de looptijd maand: 01

Het jaar: 14

Eisen

1. Semesters worden bepaald door de aangegeven maand. Bijvoorbeeld:

01 = winter

04 = lente

06 = zomer

09 = herfst

2. Voeg het programmatisch afgeleide semester en jaar toe aan de cursusnaam, gescheiden door spaties en tussen haakjes "()". Bijvoorbeeld:

Kunstgeschiedenis 202: Renaissance architectuur (winter 2014)

3. Negeer het toevoegen van informatie als er geen geschikt semester is opgegeven.

Voorwaarde achteraf

1. Aan cursussen waarvoor de course_id geschikte term-/jaar-ID's verstrekt, wordt de course_name gegevens toegevoegd met (TERM YEAR) voordat de cursusrecord in Blackboard wordt gemaakt of bijgewerkt.

2. Cursussen zonder geschikte semester-/jaaraanduidingen in de course_id worden niet course_name gewijzigd.

Script

De cursusnaam wordt opgegeven in het veld course_name de Studentinformatiesysteem-gegevensfeed en de vereiste terminformatie wordt in de Studentinformatiesysteem-gegevensfeedelementen course_id veld in numerieke indeling opgenomen. Om te voldoen aan de vereisten moeten we

a) het jaar bepalen, en

b) het semester bepalen door een bereik toe te wijzen en vervolgens de resulterende gegevens de juiste indeling te geven.

Dit doen we door JavaScript-functies te bieden om de gewenste indeling voor de weergave van de cursusnaam te retourneren en de uitvoer van deze functies in de juiste indeling te plaatsen.

a) Bepaal het jaar.

Gegeven dat de course_id een jaartal van twee cijfers bevat aan het einde van de tekenreeks, kunnen we een functie schrijven om de laatste twee tekens op te halen en terug te geven:

function courseYear(crn) {

return crn.substring(9);

}

b) Bepaal de looptijd.

De course_id biedt ons ook de gegevens om de semester te bepalen en we kunnen de JavaScript-substringfunctie gebruiken om de MM-gegevens op te halen en die toe te wijzen aan een reeks maanden die een semesterlabel vertegenwoordigen - bijvoorbeeld: 09 = herfst, 01 = winter, 04 = lente, 06 = zomer

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);

}

Omdat we hier met gehele getallen werken, kunnen we de getTerm-functie schrijven met behulp van een ‘switch’-opdracht in plaats van de bovenstaande die ‘if/else’ gebruikt ...

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 ;

}

Nu we functies hebben om het semester en jaar te bepalen, gaan we het script schrijven met de 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);

nieuweCursusnaam;

Als je het bovenstaande invoer in de veldtoewijzing voor de cursus voor Cursusnaam en, met behulp van de integratie-optie Bestand uploaden, de voorbeeldinvoer van de cursus handmatig uploadt via de bovenstaande voorwaarden vooraf, dan krijg je de onderstaande gegevens te zien in de logboeken voor onze voorbeeldcursus:

En de cursusnaam wordt nu weergegeven met het semester en het jaar zoals afgeleid van de course_id.

Wachtwoorden

Gebruik

Je gebruikt LDAP om Blackboard-gebruikers te verifiëren, maar Blackboard vereist wachtwoorden voor het maken van gebruikersaccounts en je Studentinformatiesysteem bevat geen wachtwoorden. Je moet per gebruiker een willekeurig wachtwoord maken.

Voorwaarde

De gegevensfeed biedt de basisinformatie voor de gebruiker die kan worden gebruikt om het wachtwoord op te stellen. Bijvoorbeeld: voor- en achternaam

Eisen

Wachtwoorden moeten de combinatie zijn van voornaam + achternaam + willekeurig getal

Moeten een bereik kunnen specificeren voor de randomisering

Voorwaarde achteraf

Wachtwoord is gemaakt voor gebruiker Bijvoorbeeld:

Voor de gebruiker Barney Rubble kan het wachtwoord barneyrubble102464 zijn

Voorbeeld gegevens

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

Script

function rand (min, max) {

var argc = arguments.length;

if (argc === 0) {

min = 0;

max = 2147483647;

}

return 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();

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

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

password;

Als je het bovenstaande invoert in de veldtoewijzing voor gebruikers voor Wachtwoord en de voorbeeldinvoer van de gebruiker (persoon) handmatig uploadt (opslaan) van de bovenstaande voorbeeldgegevens, dan krijg je de onderstaande gegevens in de logboeken te zien:

E-mails

Gebruik

In je Studentinformatiesysteem worden geen e-mailaccounts van Studenten opgeslagen of persoonlijke e-mailaccounts, maar niet de e-mailaccounts die door je instelling zijn uitgegeven. Je wilt dat e-mails in Blackboard de e-mailaccounts zijn die door de instelling zijn uitgegeven.

Voorwaarde

Gegevens die nodig zijn om het lokale deel van het gewenste e-mailadres te genereren, bestaan in de SIS-gegevensfeed. Bijvoorbeeld: voor- en achternaam

Eisen

Door de instelling uitgegeven e-mailaccounts volgen het patroon van [email protected] waarbij '-yy' staat voor het verwachte jaar van afstuderen voor de Student. Deze elementen worden in de volgende gegevens doorgegeven in de SIS-feed:

FIRSTNAME - de voornaam van de student

MIDDLENAME - de tweede naam van de student

LASTNAME - de achternaam van de student

OTHERNAME - het afstudeerjaar

Het lokale deel van acceptabele e-mailadressen mag alleen alfanumerieken, '-','_','.' en aanhalingsteksten bevatten. Bijvoorbeeld: Gamma.G'[email protected]

Voorwaarde achteraf

Er wordt een correct opgemaakt e-mailadres gegenereerd en doorgegeven aan Blackboard.

Voorbeeld gegevens

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

Script

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 + "). Geen e-mailadres opgeslagen voor deze gebruiker. )");

emailAddress="";

}

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

emailAddress;

Als je het bovenstaande invoert in de veldtoewijzing voor gebruikers voor Wachtwoord en de voorbeeldinvoer van de gebruiker (persoon) handmatig uploadt (opslaan) van de bovenstaande voorbeeldgegevens, dan krijg je een foutmelding in de logboeken te zien.

Dit komt omdat e-mailadressen geen uitroeptekens mogen bevatten volgens onze gewone expressie.

Opmerking: de gebruiker wordt nog steeds gemaakt omdat een geldig e-mailadres niet vereist is voor het maken of bijwerken van een gebruikersrecord.

De vermelding voor Delta Davis wijzigen van:

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

to

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

door de '!' in het achternaamveld van Delta te verwijderen en het bestand opnieuw te uploaden, wordt de fout verwijderd en wordt het record van Delta bijgewerkt met het nieuwe e-mailadres.

Een record of attribuut overslaan bij een fout

Helper biedt twee extra methoden die je nog meer controle geven over de verwerking in je scripts:

helper.skipAttribute() - slaat een niet-kritiek kenmerk over dat onjuist lijkt te zijn ingesteld

helper.skipRecord() - om het hele record over te slaan en door te gaan naar het volgende

In het bovenstaande e-mailscriptlogboek wordt een fout vastgelegd wanneer het e-mailadres niet kan worden gevalideerd, maar de record toch wordt gemaakt. Als we geen gebruikers willen maken met lege e-mails, maar in plaats daarvan de validatiefout willen vastleggen en naar de volgende record willen gaan, voegen we helper.skipRecord() toe als voorwaarde voor het e-mailadres aan het einde van het script. Bijvoorbeeld:

in plaats van het script te sluiten met emailAddress=""; Sluit het af met:

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

Hiermee wordt de record voorwaardelijk overgeslagen op basis van de inhoud van het emailAddress dat we hebben ingesteld als een lege tekenreeks wanneer de validatie is mislukt.

Voeg de methode helper.skipRecord() toe aan het script en wijzig de regel voor Delta Davis van:

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

to

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

Als je het gewijzigde - met uitroepteken - invoervoorbeeld van de gebruiker (persoon) handmatig uploadt (opslaat), krijg je de gegevens in de logboeken te zien.

Opmerking: de fout wordt vastgelegd en aan het einde van het logboek zie je dat de record is overgeslagen als gevolg van het toewijzingsscript en het attribuut dat het resultaat heeft geretourneerd.

Het voorwaardelijk toepassen van helper.skipAttribute() heeft een vergelijkbare impact: het script verwerkt de feedgegevens en op basis van de aanwezigheid van een voorwaardelijke als de laatste regel die helper.skipAttribute() aanroept, zal de integratie een fout genereren en het record overslaan, of, als het kenmerk niet vereist is, neemt de toewijzingsconfiguratie de controle over en behandelt het kenmerk zoals geconfigureerd.