Asignación de campos personalizados de archivo de instantánea sin formato

Asignación de campo

El marco SIS o Sistema de información del estudiante admite la personalización de los datos entrantes antes de agregarlos a Blackboard registro por registro. Esto es útil cuando los datos de su sistema SIS o Sistema de información del estudiante no están alineados con sus requisitos de datos de Blackboard y no se pueden modificar en el SIS o Sistema de información del estudiante porque es prohibitivo o la información que representan los datos es utilizada por otros sistemas. En este documento, se trata el uso de la opción "Asignación de campos", concretamente el uso de la opción de asignación del campo Secuencia de comandos personalizada.

Esta función de personalizar los datos entrantes se denomina asignación de campos y se accede a ella desde la interfaz de usuario en el menú de configuración avanzada de la integración.

La pantalla Configuración avanzada proporciona una lista de los objetos compatibles con ese objeto en Blackboard. Estos se ajustan al tipo de integración y varían de un tipo de integración a otro.

Si selecciona Asignación de campos en un objeto de Learn asociado al tipo de integración, en este caso Cursos, se le dirigirá a la página Asignación de campos de la integración.

Además de la información útil relativa al campo, como si es necesario para la inserción o si debe ser único, también puede seleccionar varias opciones que controlan cómo se administran los datos entrantes en la integración y si desea asignar objetos entrantes.

Scripts personalizados y asignación de campos

En el campo en el que desea proporcionar una asignación de campo, puede seleccionar que se utilice un campo entrante diferente. Por ejemplo: supongamos que el ID del curso entrante no es adecuado para su uso en Blackboard, pero en su lugar puede asignarlo a la clave externa del curso. Debido a que este tutorial trata sobre el uso de una secuencia de comandos personalizada para realizar la asignación, debe seleccionar "Usar una secuencia de comandos personalizada" en el menú desplegable "Campo de origen".

Las secuencias de comandos personalizadas se basan en JavaScript. Todos los datos entrantes se asignan a un modelo de objetos interno que proporciona la capacidad de acceder a cada elemento de datos para ver sus datos, usarlos y manipularlos con JavaScript personalizado.

Utilice comparadores de enteros en las instrucciones switch de JavaScript. Si debe utilizar cadenas o caracteres como comparadores, utilice instrucciones if/else en lugar de instrucciones switch.

Dos excelentes referencias de JavaScript son proporcionadas por Mozilla Developer Network https://developer.mozilla.org/en-US/...ript/Reference y el World Wide Web Consortium (W3C) http://www.w3instituto.com/jsref/.

Si selecciona "Usar una secuencia de comandos personalizada", aparece un área de texto para que ingrese el código JavaScript.

Aquí ingresará la secuencia de comandos personalizada para editar los datos entrantes.

Documentación de In-Blackboard

La documentación sobre los scripts de asignación de campos personalizados se encuentra en la página Documentos de muestra vinculada desde la página Integraciones del sistema de información de estudiantes de nivel superior en el Panel del administrador de Blackboard.

El enlace Documentos de muestra abre una página que contiene varios enlaces a documentos del marco de trabajo de integración SIS que abarcan todos los tipos de integración. Los dos documentos de interés en el contexto del tipo de integración de archivo sin formato de instantánea y la asignación de campos personalizados están vinculados por el diccionario de datos: Ejemplos de secuencia de comandos de integración de archivos sin formato de instantáneas y asignación de campos personalizados, respectivamente.

Scripts personalizados

El acceso al modelo de objetos de cada tipo de integración es diferente y se basa en la estructura de datos subyacente de la especificación de datos del tipo de integración. A partir de una comprensión de la especificación de datos de integración, se puede derivar un patrón para acceder a todos los objetos de la integración.

En el caso del archivo de instantánea sin formato, este patrón se basa en un objeto raíz de "datos", por lo que podemos derivar el siguiente patrón:

data.getValue(<FlatFileDataObject>);

donde <FlatFileDataObject> se reemplaza por el nombre del elemento de encabezado de la fuente de datos.

Por ejemplo:

data.getValue("firstname");

data.getValue("lastname");

data.getValue("course_name");

Además, cuando la fuente de distribución de datos toma una "Y" o "N", debe reemplazar condicionalmente como resultado del script los valores booleanos true o false respectivamente. Por ejemplo:

var avail_ind = false;

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

avail_ind=true;

avail_ind;

o, alternativamente, escribir una instrucción utilizando un operador ternario:

condición? ejecutar si condición true: ejecutar si condición false :

Por ejemplo:

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

avail_ind;

lo anterior puede reducirse aún más a solo la instrucción ternaria, ya que es el valor final de la expresión en la última línea del script que se devuelve como el punto de datos guardado en Blackboard.

Así que podemos usar:

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

y obtener el mismo resultado.

Dado que las secuencias de comandos personalizadas se procesan por cada registro, el rendimiento de la integración puede verse afectado si se ejecutan secuencias de comandos de cálculo intensivo (como el cifrado). Tenga en cuenta que no es posible acceder a datos externos; solo puede realizar operaciones con datos de fuentes existentes o con datos derivados por cálculo.

Depuración de scripts

Resulta relativamente sencillo depurar las secuencias de comandos, ya que se registran los errores o problemas de datos que pueda encontrar.

Por ejemplo:

Dado el desarrollo de una secuencia de comandos personalizada en el campo "Disponible":

data.getValue("available_ind");

se puede ejecutar correctamente, pero si el valor no se pasa en la fuente de datos, la secuencia de comandos generará la siguiente entrada en el registro:

Valor nulo devuelto para el atributo que no acepta valores NULL: isAvailable.

Datos no válidos para el atributo: isAvailable. Valor: null. Usando el valor predeterminado de Blackboard.

Mientras que (suponiendo que se proporciona available_ind en la fuente):

data.getValue("available_ind");

puede ejecutarse correctamente, pero producir la siguiente entrada en el registro:

Tipo de valor no válido para attribute: isAvailable. Valor: y

Datos no válidos para el atributo: isAvailable. Valor: Y. Usando el valor predeterminado de Blackboard.

Esto se debe a que necesitamos alterar condicionalmente los datos entrantes al valor booleano esperado, en este caso "TRUE", por lo que podríamos cambiar el script a:

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

Pero para mayor seguridad, necesitamos capturar las comparaciones entre mayúsculas y minúsculas, así que modificamos la secuencia de comandos:

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

Esto provocará un error de secuencia de comandos real y se mostrará en el registro:

Error en la ejecución del script para el atributo: isAvailable.

blackboard.platform.script.ScriptingException: javax.script.ScriptException: sun.org.mozilla.javascript.internal.EcmaError: ReferenceError: "toUpper" no está definido. (<Fuente desconocida>#2) en <Fuente desconocida> en la línea número 2

Esto se debe a que JavaScript no tiene toUpper(), pero sí tiene toUpperCase() por lo que editar el script...

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

y ahora la secuencia de comandos se ejecutará correctamente.

Scripts auxiliares: Registro en scripts personalizados

Blackboard proporciona scripts auxiliares para proporcionar capacidades comunes, como el registro de sus scripts. Si agrega lo siguiente a las secuencias de comandos, se incluirá el resultado en los registros de integración:

helper.logError(msg)

helper.logWarning(msg)

helper.logInfo(msg)

helper.logDebug(msg)

El resultado de los métodos helper.log* se mostrará en los registros en función de la configuración de la integración para los niveles de registro.

Los scripts auxiliares adicionales disponibles (como se describe en la página Ejemplos de scripts de asignación de campos personalizados vinculada desde la página Documentos de muestra) son:

Continuando con nuestro script de muestra, agregaremos un mensaje de registro de información para indicar que el valor utilizado en Blackboard se deriva de un script personalizado, el objeto de datos base al que se hace referencia para los datos insertados y los valores calculados que se usaron. También agregaremos un mensaje de registro que indique una condición de error basada en la falta de una secuencia de comandos adecuada disponible.

Si volvemos a lo anterior, supongamos que AVAILABLE_IND se establece de forma irregular en las fuentes de datos del curso, es decir, que no siempre está presente en la fuente de datos, y que desea establecerlo en "true" cuando un valor de AVAILABLE_IND no está presente o evaluarlo de otro modo de forma adecuada? La secuencia de comandos se convierte ahora de la siguiente manera:

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;

El registro muestra lo siguiente:

31 de mayo de 2013 4:03:56 PM - Curso [crear/actualizar, examenCourse1]

INCOMING AVAILABLE_IND UNDEFINED para TEST_COURSE_1: el valor isAvailable en true

OUTGOING AVAILABLE_IND: [true]

El curso 'testCourse1' se procesó correctamente.

testCourse1|TEST_COURSE_1|Test Course 1|

...

entradas de registro restantes

...

Asignación de campos exitosa.

Ejemplos

Nombre del curso: Agregar término y año

Caso de uso

Se desea que la visualización de los cursos contenga el período y el año en que se ofrece el curso. Actualmente, los datos que proporciona el SIS no anexan esta información al course_name. Los cursos se muestran con el nombre del curso. Por ejemplo:

Condiciones previas

El SIS proporciona el período y el año como parte de la cadena de course_id y proporciona el campo de course_name obligatorio.

Por ejemplo:

external_course_key|course_id|course_name|available_ind

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

In the above example the course_id is comprised of:

el departamento: 36

el curso: 202

la sección: 01

el trimestre mes: 01

el año: 14

Requisitos

1. Los períodos son determinados por el mes designado. Por ejemplo:

01 = Invierno

04 = Primavera

06 = Verano

09 = Otoño

2. Agregue al nombre del curso el período y el año derivados mediante programación, separados por espacios y encerrados entre paréntesis "()". Por ejemplo:

Historia del Arte 202: Arquitectura renacentista (invierno de 2014)

3. Ignore la información adjunta si no se proporciona el período adecuado.

Condición posterior

1. Los cursos en los que course_id proporcione identificadores de período/año adecuados tendrán sus datos de course_name adjuntos con (AÑO DEL PERÍODO) antes de crear o actualizar el registro del curso en Blackboard.

2. A los cursos que no tengan identificadores adecuados de período/año en el course_id no se les cambiará el course_name.

Secuencia de comandos

El nombre del curso se proporciona en el campo course_name de la fuente de datos del SIS y la información obligatoria del período se incluye en el campo course_id de los elementos de la fuente de datos del SIS en formato numérico. Para cumplir con los requisitos se necesita lo siguiente:

a) determinar el año y

b) determinar el período mediante la asignación a un intervalo y, a continuación, formatear correctamente los datos resultantes.

Esto se hará proporcionando funciones de JavaScript que devolverán el formato deseado para la visualización del nombre del curso y colocarán la salida de esas funciones en el formato adecuado.

a) Determinar el año.

Dado que course_id contiene un año de dos números al final de la secuencia de caracteres, se puede escribir una función para extraer y devolver los dos últimos caracteres:

function courseYear(crn) {

return crn.substring(9);

}

b) Determinar el plazo.

El course_id también nos proporciona los datos para determinar el período y podemos usar la función de subcadena de JavaScript para extraer los datos MM y asignarlos a un rango de meses que representan una etiqueta de período: por ejemplo: 09 = Otoño, 01 = Invierno, 04 = Primavera, 06 = Verano

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

}

Dado que en este caso se trabaja con números enteros, se podría escribir la función getTerm utilizando una instrucción switch en lugar de la anterior, que utiliza 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 ;

}

Ahora que se tienen funciones para determinar el período y el año, se escribe la secuencia de comandos que agrega el 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;

Si se ingresa lo anterior en la asignación del campo Curso para Nombre del curso y, si se utiliza la opción Cargar archivo de la integración, para cargar (almacenar) manualmente el ejemplo de fuente del curso según la condición previa mencionada anteriormente, se verán los siguientes datos publicados en los registros del curso de muestra:

El nombre del curso ahora se mostrará con el período y el año que se derivan de course_id.

Contraseñas

Caso de uso

Puede utilizar LDAP para autenticar a los usuarios de Blackboard, pero Blackboard requiere contraseñas para crear cuentas de usuario y su SIS o Sistema de información del estudiante no proporciona contraseñas. Debe crear una contraseña aleatoria para cada usuario.

Condiciones previas

La fuente de datos proporciona la información básica del usuario que se puede utilizar para crear la contraseña. Por ejemplo: nombre y apellido

Requisitos

Las contraseñas deben ser la combinación de nombre+apellido+número aleatorio

Debe poder especificar un intervalo para la aleatorización

Condición posterior

Se crea la contraseña para el usuario. Por ejemplo:

Para el usuario Barney Rubble, la contraseña podría ser barneyrubble102464

Datos de muestra

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

Secuencia de comandos

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;

Si se ingresa lo anterior en la asignación del campo Usuario para Contraseña y se carga (almacena) manualmente el ejemplo de fuente Usuario (Persona) a partir de los datos de muestra anteriores, se verán los siguientes datos publicados en los registros:

Correos electrónicos

Caso de uso

Su SIS o Sistema de información del estudiante no almacena las cuentas de correo electrónico de los estudiantes o almacena las cuentas de correo electrónico personales, pero no las emitidas por su institución: desea que los correos electrónicos en Blackboard sean las cuentas de correo electrónico emitidas por la institución.

Condiciones previas

Los datos necesarios para generar la parte local de la dirección de correo electrónico deseada existen en la fuente de datos del SIS. Por ejemplo: nombre y apellido

Requisitos

Las cuentas de correo electrónico emitidas por la institución siguen el patrón de [email protected] donde '-yy' representa el año anticipado de graduación para el estudiante. Estos elementos se pasan en la fuente del SIS con los siguientes datos:

FIRST_NAME: el nombre del estudiante

MIDDLENAME: el segundo nombre del estudiante

LAST_NAME: el apellido del estudiante

OTHERNAME: el año de graduación

La parte local de las direcciones de correo electrónico aceptables debe contener solo elementos alfanuméricos, '-','_','.' y apóstrofos. Por ejemplo: Gamma.G'[email protected]

Condición posterior

Se genera una dirección de correo electrónico con el formato adecuado y se pasa a Blackboard.

Datos de muestra

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

Secuencia de comandos

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;

Si se ingresa lo anterior en la asignación del campo Usuario para Contraseña y se carga (almacena) manualmente el ejemplo de fuente Usuario (Persona) a partir de los datos de muestra anteriores, se verá un error publicado en los registros.

Esto se debe a que las direcciones de correo electrónico no pueden contener signos de exclamación según la expresión regular.

Tenga en cuenta que el usuario se crea de todos modos, ya que no se requiere una dirección de correo electrónico válida para crear o actualizar un registro de usuario.

Se cambia la entrada para Delta Davis de:

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

a

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

al eliminar el signo '!' del campo lastname de Delta y volver a cargar el archivo, se elimina el error y se actualiza el registro de Delta con la nueva dirección de correo electrónico.

Omitir un registro o atributo por error

"Helper" proporciona dos métodos adicionales que permiten un control aún mayor sobre el procesamiento en las secuencias de comandos:

helper.skipAttribute(): omite un atributo no crítico que parece estar configurado incorrectamente

helper.skipRecord() : para omitir todo el registro y pasar al siguiente

La secuencia de comandos de correo electrónico anterior registra un error cuando no se puede validar la dirección de correo electrónico, pero igualmente sigue creando el registro. Si no quisiéramos crear usuarios con correos electrónicos en blanco, sino registrar el error de validación y pasar al siguiente registro, agregaríamos helper.skipRecord() en un condicional basado en emailAddress al final de la secuencia de comandos. Por ejemplo:

en lugar de cerrar la secuencia de comandos con emailAddress=""; cerrarla con:

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

Esto omite de forma condicional el registro basado en el contenido de emailAddress que configuramos para que sea una cadena en blanco cuando falla la validación.

Agregue el método helper.skipRecord() a la secuencia de comandos y cambie la entrada para Delta Davis de:

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

a

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

Si carga (almacena) manualmente el ejemplo de fuente Usuario (Persona) revisado (con signo de exclamación), verá los datos publicados en los registros.

Observe que el error se registra y que en la parte inferior se indica que el registro se omitió como resultado de la secuencia de comandos de asignación y el atributo que devolvió el resultado.

La aplicación condicional de helper.skipAttribute() tendrá un impacto similar. La secuencia de comandos procesará los datos de la fuente y, en función de la presencia de una condicional como línea final de la llamada a helper.skipAttribute(), la integración arrojará un error y omitirá el registro o, si el atributo no es necesario, la configuración de asignación controlará y gestionará el atributo según lo configurado.