스냅샷 플랫 파일 사용자 지정 필드 매핑

필드 매핑

학생 정보 시스템 프레임워크는 Blackboard에 기록을 추가하기 전에 수신 데이터를 사용자가 정의할 수 있도록 지원합니다. 학생 정보 시스템의 데이터가 Blackboard 데이터 요구 사항과 일치하지 않거나 변경이 금지되어 있고, 해당 데이터가 다른 시스템에서 사용될 때 유용합니다. 이 문서에서는 '필드 매핑' 옵션의 사용, 특히 사용자 지정 스크립트 필드 매핑 옵션을 사용하는 방법에 대해 설명합니다.

수신 데이터를 사용자 지정하는 이 기능은 필드 매핑이라고 하며 통합의 고급 구성 메뉴 아래에 있는 UI에서 접근할 수 있습니다.

고급 구성 화면은 Blackboard에서 지원하는 해당 객체 목록을 제공합니다. 이는 통합 유형에 맞게 조정되며 통합 유형마다 달라집니다.

통합 유형(이 경우 코스)과 연계된 Learn 객체에서 필드 매핑을 선택하면 통합을 위한 필드 매핑 페이지로 이동됩니다.

삽입에 필요한지 또는 고유해야 하는지 여부처럼 필드와 관련된 유용한 정보 외에도 통합에서 수신 데이터를 관리하는 방법과 수신 객체 간에 매핑하도록 선택할지 여부를 제어하는 여러 설정을 선택할 수도 있습니다.

사용자 정의 스크립트 및 필드 매핑

필드 매핑을 제공하려는 필드에서 다른 수신 필드를 사용하도록 선택할 수 있습니다. 예를 들어, 코스 ID가 Blackboard에서 사용하기 적합하지 않은 경우 대신 코스 외부 키에 매핑할 수 있습니다. 이 튜토리얼은 사용자 지정 스크립트를 사용하여 매핑을 수행하는 방법에 관한 것이므로 '소스 필드' 풀다운에서 '사용자정의 스크립트 사용'을 선택합니다.

사용자 지정 스크립트는 JavaScript를 기반으로 합니다. 모든 수신 데이터는 내부 객체 모델에 매핑되어 각 데이터 요소에 접근하여 데이터에 대한 후속 사용 또는 사용자 지정 JavaScript를 사용하여 조작할 수 있는 기능을 제공합니다.

JavaScript switch 문에서는 정수 비교기를 사용합니다. 문자열 또는 문자를 비교기로 사용해야 하는 경우 switch 문 대신 if/else 문을 사용합니다.

Mozilla Developer Network https://developer.mozilla.org/ko-KR/...ript/Reference 및 W3C(World Wide Web Consortium) http://www.w3schools.com/jsref/에서 우수한 JavaScript 참조 자료 두 가지를 제공합니다.

'사용자정의 스크립트 사용'을 선택하면 자바 스크립트 코드를 입력 할 수 있는 텍스트 영역이 제공됩니다.

이 텍스트 영역에서 사용자 지정 스크립트를 입력하여 수신 데이터를 수정하게 됩니다.

Blackboard 설명서

사용자 정의 필드 매핑 스크립트에 관한 문서는 Blackboard 관리자 패널의 최상위 수준 학생 정보 시스템 통합 페이지에 연결된 샘플 문서 페이지에서 확인할 수 있습니다.

샘플 문서 링크를 클릭하면 모든 통합 유형을 다루는 SIS 통합 프레임워크 문서에 대한 링크 여러 개가 포함된 페이지가 열립니다. 두 문서는 각각 데이터 사전에 의해 링크되며, 스냅숏 플랫 파일 통합 및 사용자 지정 필드 매핑의 맥락에서 관심을 가질 만합니다(스냅숏 플랫 파일 통합 및 사용자 지정 필드 매핑 스크립트 예제).

사용자 정의 스크립트

각 통합 유형의 객체 모델에 대한 접근은 서로 다르며 통합 유형 데이터 사양의 기본 데이터 구조를 기반으로 합니다. 통합 데이터 사양을 이해하면 모든 통합 객체에 접근하는 패턴을 도출할 수 있습니다.

스냅샷 플랫 파일의 경우 이 패턴은 'data'의 루트 객체를 기반으로 하므로 다음 패턴을 도출할 수 있습니다.

data.getValue(<FlatFileDataObject>);

여기서 <FlatFileDataObject>는 데이터 피드의 헤더 요소 이름으로 대체됩니다.

예:

data.getValue("firstname");

data.getValue("lastname");

data.getValue("course_name");

데이터 피드에서 'Y'나 'N'을 사용할 경우, 스크립트 결과를 조건에 따라 부울 값 true나 false로 변환해야 합니다. 예:

var avail_ind = false;

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

avail_ind=true;

avail_ind;

또는 삼항 연산자를 사용하는 using 명령문을 사용하여 작성됩니다.

조건? 조건이 참일 경우 실행: 조건이 거짓일 경우 실행:

예:

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

avail_ind;

위 내용은 Blackboard에 저장된 데이터 포인트로 반환되는 스크립트 마지막 줄에 있는 표현식의 최종 값을 나타내므로 삼항 연산자를 사용하여 더 간단하게 표현할 수 있습니다.

따라서 다음을 사용할 수 있습니다.

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

그리고 동일한 결과를 얻습니다.

사용자 지정 스크립트가 기록 단위로 처리된다는 점을 감안할 때 계산 집약적인 스크립트(예: 암호화)를 수행하는 경우 통합 성능에 영향을 미칠 수 있습니다. 또한 외부 데이터 접근은 지원되지 않으며 기존 피드 데이터 또는 계산 방식으로 파생된 데이터에 대해서만 작업을 수행할 수 있습니다.

디버깅 스크립트

스크립트를 디버깅하면 발생할 수 있는 오류 또는 데이터 문제가 기록되므로 비교적 쉽습니다.

예:

'사용 가능한' 필드에 대한 사용자 지정 스크립트의 개발을 고려할 경우:

data.getValue("available_ind");

이는 성공적으로 실행될 수 있지만, 값이 데이터 피드에 전달되지 않으면 스크립트가 로그에 다음 항목을 생성하게 됩니다.

특성이 null을 허용하지 않을 때 반환된 Null 값: isAvailable.

속성에 대한 데이터가 잘못되었습니다: 이(가) 사용 가능합니다. 값: null. Blackboard 기본값을 사용합니다.

반면(피드에 available_ind가 제공된다고 가정):

data.getValue("available_ind");

이는 성공적으로 실행될 수 있지만, 로그에 다음 항목이 생성됩니다.

attribute:의 isAvailable에 잘못된 값 유형이 지정되었습니다. 값: y

속성에 대한 데이터가 잘못되었습니다: 이(가) 사용 가능합니다. 값: Y. 기본 블랙보드 값을 사용합니다.

이는 들어오는 데이터를 예상된 부울 값(이 경우 "TRUE")으로 조건부로 변경해야 하므로 스크립트를 다음과 같이 변경할 수 있습니다.

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

그러나 원칙대로 하려면 대문자와 소문자 비교를 캡처해야 하므로 스크립트를 조정합니다.

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

이렇게 하면 실제 스크립트 오류가 발생하고 로그에 다음과 같이 인쇄됩니다.

속성에 대한 스크립트 실행 오류: 이용 가능.

blackboard.platform.script.ScriptingException: javax.script.ScriptException: sun.org.mozilla.javascript.internal.EcmaError: ReferenceError: "toUpper"가 정의되지 않았습니다. (<Unknown Source>#2) <Unknown Source>의 2행

JavaScript에는 toUpper() 함수가 없고 toUpperCase() 함수가 있기 때문에 스크립트를 편집하는 것입니다.

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

이제 스크립트가 성공적으로 실행됩니다.

도우미 스크립트: 사용자 지정 스크립트 로그인

블랙보드는 스크립트 로깅과 같은 일반 기능을 지원하기 위한 도우미 스크립트를 제공합니다. 스크립트에 다음을 추가하면 통합 로그에 출력이 포함됩니다.

helper.logError(msg)

helper.logWarning(msg)

helper.logInfo(msg)

helper.logDebug(msg)

로깅 수준에 대한 통합 구성에 따라 helper.log* 메서드의 출력이 로그에 표시됩니다.

추가로 사용할 수 있는 도우미 스크립트(샘플 문서 페이지에 링크된 사용자 정의 필드 매핑에 대한 예시 페이지에서 설명된 바와 같이)는 다음과 같습니다.

샘플 스크립트를 진행하는 중 Blackboard에 사용된 값이 사용자 정의 스크립트, 삽입된 데이터, 기본 데이터 객체에서 참조되고 사용된 계산된 값에서 파생되었다는 정보 로그 메시지를 추가합니다. 또한 적절하고 사용 가능한 항목이 없는 경우를 기준으로 오류 조건을 나타내는 로그 메시지도 추가할 예정입니다.

위의 스크립트를 다시 살펴봅니다. AVAILABLE_IND가 코스 데이터 피드에 일관되지 않게 설정되어 있고(즉, 데이터 피드에 항상 존재하는 것은 아님) AVAILABLE_IND 값이 존재하지 않을 때 이를 true로 설정하거나 다른 방법으로 적절하게 평가한다고 가정해 보겠습니다. 이제 스크립트는 다음과 같이 됩니다.

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;

이제 로그에 다음과 같이 표시됩니다.

2013년 05월 31일 오후 4시 03분 56초 - 코스 [만들기/업데이트, testCourse1]

TEST_COURSE_1에 대해 INCOMING AVAILABLE_IND UNDEFINED: isAvailable을 true로 설정합니다.

OUTGOING AVAILABLE_IND: [true]

‘testCourse1’ 과정이 성공적으로 처리되었습니다.

testCourse1|TEST_COURSE_1|Test Course 1|

...

나머지 로그 항목

...

필드 매핑이 성공적으로 완료되었습니다.

예

코스 이름: 학기 및 연도 추가

사용 사례

코스 화면표시에는 코스가 제공되는 학기와 연도가 포함되는 것이 좋습니다. 현재 SIS에서 제공하는 데이터는 course_name에 이 정보를 덧붙이지 않습니다. 코스는 코스 이름을 사용하여 표시됩니다. 예:

전제 조건

SIS에서는 학기 및 연도를 course_id 문자열의 일부로 제공하고 필수 course_name 필드를 제공합니다.

예:

external_course_key|course_id|course_name|available_ind

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

위 예에서 'course_id'는 다음과 같이 구성됩니다.

부서: 36

코스: 202

섹션: 01

학기 시작 월: 01

연도: 14

요구사항

1. 학기는 지정된 달을 기준으로 결정됩니다. 예:

01 = 겨울

04 = 봄

06 = 여름

09 = 가을

2. 프로그래밍 방식으로 파생된 학기와 연도를 코스명에 추가하고 공백으로 구분하여 괄호 "()"로 묶어 추가합니다. 예:

미술사 202: 르네상스 건축(2014년 겨울)

3. 적절한 학기가 제공되지 않는 경우 추가 정보를 무시합니다.

사후 조건

1. course_id에서 적절한 학기 및 연도 식별자를 제공하는 코스는 Blackboard에서 코스 기록을 생성하거나 업데이트하기 전에 course_name 데이터에 (학기 연도)를 추가합니다.

2. course_id에 적절한 학기/연도 식별자가 없으면 course_name은 변경되지 않습니다.

스크립트

코스명은 SIS 데이터 피드 course_name 필드에 제공되며 필수 학기 정보는 SIS 데이터 피드 요소 course_id 필드에 숫자 형식으로 저장됩니다. 요구 사항을 충족하려면 다음을 수행해야 합니다.

a) 연도를 결정합니다.

b) 범위에 매핑하여 학기를 결정한 다음 결과 데이터의 형식을 적절하게 지정합니다.

코스명 표시를 위해 원하는 형식을 반환하고 해당 함수의 출력을 적절한 형식으로 배치하는 javascript 함수를 제공하여 이를 수행합니다.

a) 연도를 결정합니다.

course_id의 문자 시퀀스 끝에 두 자리 연도가 포함되어 있다면, 마지막 두 자리를 추출하여 반환하는 함수를 작성할 수 있습니다.

function courseYear(crn) {

return crn.substring(9);

}

b) 용어를 결정한다.

course_id는 학기 결정에 필요한 데이터도 제공하고, JavaScript 하위 문자열 함수를 사용해 MM 데이터를 추출하여 월 범위에 해당하는 학기 레이블로 매핑할 수 있습니다. 예: 09=가을, 01=겨울, 04=봄, 06=여름

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

}

여기서는 정수로 작업하고 있기 때문에 if/else를 사용하는 위의 문 대신 switch 문을 사용하여 getTerm 함수를 작성할 수 있습니다.

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 ;

}

이제 학기와 연도를 결정하는 함수가 있으므로 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;

코스명에 대한 코스 필드 매핑에 위 내용을 입력하고 통합 파일 업로드 옵션을 사용하여 위 전제 조건의 코스 피드 예를 수동으로 업로드(저장)하면 샘플 코스의 로그에 아래와 같은 데이터가 게시된 것을 볼 수 있습니다.

코스 이름이 이제 course_id에서 파생된 학기 및 연도와 함께 표시됩니다.

비밀번호

사용 사례

Blackboard 사용자 인증에 LDAP를 사용하지만, 사용자 계정을 Blackboard에서 생성하려면 비밀번호가 필요하고 학생 정보 시스템은 비밀번호를 제공하지 않습니다. 사용자별로 임의의 비밀번호를 만들어야 합니다.

전제 조건

데이터 피드는 비밀번호를 작성하는 데 사용할 수 있는 기본 사용자 정보를 제공합니다. 예: 이름 및 성

요구사항

비밀번호는 firstname+lastname+난수의 조합이어야 합니다.

무작위 추출 범위를 지정할 수 있어야 합니다.

사후 조건

사용자의 비밀번호가 생성됩니다. 예를 들면 다음과 같습니다.

사용자 Barney Rubble의 경우 비밀번호는 barneyrubble102464일 수 있습니다.

샘플 데이터

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

스크립트

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;

위의 내용을 비밀번호에 대한 사용자 필드 매핑에 입력하고 위의 샘플 데이터에서 사용자(개인) 피드 예를 수동으로 업로드(저장)하면 로그에 아래 데이터가 가 게시되는 것을 볼 수 있습니다.

이메일

사용 사례

SIS는 학생 개인 이메일 계정은 저장하지만 교육기관에서 발급한 이메일은 저장하지 않습니다. - Blackboard에서 사용할 이메일을 교육기관에서 발급한 계정으로 설정하려 합니다.

전제 조건

원하는 이메일 주소의 로컬 부분을 생성하는 데 필요한 데이터가 SIS 데이터 피드에 있습니다. 예: 이름 및 성

요구사항

기관에서 발급한 이메일 계정은 [email protected]에서 '-yy'는 학생의 예상 졸업년도를 의미합니다. 이러한 요소는 SIS 피드에서 다음 데이터로 전달됩니다.

FIRSTNAME - 학생의 이름

MIDDLENAME - 학생의 중간 이름

LASTNAME - 학생의 성

OTHERNAME - 졸업 연도

허용되는 이메일 주소의 로컬 부분에는 영숫자, '-','_','.' 및 아토론글로피만 포함되어야 합니다. Gamma.G'[email protected]

사후 조건

이메일 주소가 올바른 형식으로 생성되어 Blackboard로 전달됩니다.

샘플 데이터

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

스크립트

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;

위의 내용을 비밀번호에 대한 사용자 필드 매핑에 입력하고 위의 샘플 데이터에서 사용자(개인) 피드 예를 수동으로 업로드(저장)하면 로그에 오류가 게시되는 것을 볼 수 있습니다.

정규식에 따라 이메일 주소에는 느낌표를 포함할 수 없기 때문입니다.

사용자 기록을 생성하거나 업데이트하는 데 유효한 이메일 주소가 필요하지 않으므로 사용자가 계속 생성됩니다.

Delta Davis에 대한 항목 변경:

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

->

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

델타의 성 필드에서 '!'를 제거하고 파일을 다시 업로드하면 오류가 해결되며 델타의 기록이 새 이메일 주소로 갱신됩니다.

오류가 발생하면 레코드나 속성을 건너뛰세요.

도우미는 스크립트의 처리를 더 잘 제어할 수 있는 다음 두 가지 추가 메서드를 제공합니다.

helper.skipAttribute() - 중요하지 않은 잘못 설정된 속성을 건너뜁니다.

helper.skipRecord() - 전체 레코드를 건너뛰고 다음 레코드로 넘어갑니다.

위의 이메일 스크립트는 이메일 주소의 유효성을 검사할 수 없을 때 오류를 기록하지만 어쨌든 기록은 계속해서 생성합니다. 이메일이 비어 있는 사용자를 생성하지 않고 대신 유효성 검사 오류를 기록하고 다음 기록으로 이동하려는 경우 스크립트 끝에 있는 emailAddress를 기반으로 조건부에 helper.skipRecord()를 추가합니다. 예:

emailAddress=""로 스크립트를 닫는 대신, 다음과 같이 닫습니다.

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

이렇게 하면 유효성 검사에 실패했을 때 빈 문자열로 설정한 emailAddress의 내용에 따라 조건부로 기록을 건너뜁니다.

helper.skipRecord() 메서드를 스크립트에 추가하고 Delta Davis에 대한 항목을 다음과 같이 변경합니다.

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

->

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

느낌표가 있는 수정된 사용자(개인) 피드 예를 수동으로 업로드(저장)하면 로그에 게시된 데이터를 볼 수 있습니다.

오류가 기록되고 로그의 끝에는 결과를 반환한 속성 및 매핑 스크립트의 결과로 기록을 건너뛰었다는 내용이 기록됩니다.

조건부로 helper.skipAttribute()를 적용해도 유사한 영향을 미칩니다. 스크립트가 피드 데이터를 처리하고 helper.skipAttribute()를 호출하는 마지막 줄로 조건부의 존재 여부에 따라 통합에서 오류가 발생하고 기록을 건너뛰거나 속성이 필요하지 않은 경우 매핑 구성이 제어하고 구성된 대로 속성을 처리합니다.