Quercus Live Link Developer’s Guide<>

URL construction – students and other persons

Information available

From version 8.3.1 onwards Live Link will be used to allow third-party integrators make calls to Quercus for information in the following areas:

information about a person

information about a person on a course instance

information about notes particular to a person

information about courses or course instances

information about existing interactions

information about modules or module instances

information about course curriculum

information about student curriculum

The existing package QLL_WEB (Quercus Live Link) will be modified to handle requests for information about persons/users and students.

The distinction between a person and a student is important. A person is any person held in Quercus be they a student, administrative staff, directors, contacts etc. A student is a person who is associated with a course or activity.

There will be new query categories available to query. These will be distinguished in the URL by the query-category modifier that will follow the solar.qll_web namespace:

Query category

Query category modifier

Queries about a specific person

solar.qll_web.person?

Queries about a specific student

solar.qll_web.enrolment?

Queries about person notes

solar.qll_web.person_note?

Queries about courses/Course Instances

solar.qll_web.courses?

Queries about existing applications

solar.qll_web.interactions?

Queries about modules/module instances

solar.qll_web.modules?

Queries about course curriculum

solar.qll_web.course_structure?

Queries about student curriculum

solar.qll_web.curriculum?

The existing security mechanisms used in Quercus Live Link will be in place for the deployment of this extension to the package, information about the deployment and security is available in the Quercus Live Link documentation.

Biographical data – information about a person

A new person API will provide biographical information about a particular person based on a parameter passed into the API from the calling service. The following information about the person will be made available to the calling service:

Global Unique Identifier (GUID)

ID Number

First Name, Surname, Middle Name, Preferred Name, Title, Gender, Social Insurance Number, Date of Birth, Date Deceased

Home Address

Term Address

Work Address

Mailing Label

A list of the persons roles

A list of the person persons reference numbers

The persons domicile, nationality, ethnic grouping and socio economic grouping

Each address will consist of:

Address Line 1

Address Line 2

Address Line 3

Address Line 4

Address Line 5

Postcode

Phone

Fax

Email

Contact

Mobile Phone

Information about a person will be presented in the same XML format as that used for the event-driven messaging. See Quercus Message Link Reference Guide & Message Specifications – Section 4.7 B1-Biographical Data (OUT) for a full details.

At least of the following parameters can be used to obtain information about a person:

Parameter name

Description

Example

userName

The users LDAP username

solar.qll_web.person?username=jbloggs

id

The users quercus id number

solar.qll_web.person?id=123456

guid

The users Global Unique Identifier – often the same as the id number but can be different

solar.qll_web.person?guid=123456_AA01

If all parameters are null or if the person is not found based on any of the passed parameters then a XML will return a ‘Person Not Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(GUID:ID:USERNAME:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if GUID and Username were null then the following should be hashed:

(:ID::AUTH_KEY)

Information about a person on a course instance

The new enrolment API will provide information about a particular person and their enrolments (STUDENT_COURSE_DETAIL). Depending on the parameters passed into the URL the feed will return:

Details of a specific enrolment

All enrolments for the person

All enrolments for the person for a specific academic session

Information about enrolments will be presented in much the same XML format as that used for the event-driven messaging (see document Quercus Message Link Reference Guide & Message Specifications – Section 4.13 E1-Student Enrolment (OUT) for full details), however, when multiple enrolments are returned by the query each course instance will be nested below an enrolments tag. Also included will be information about the course/course instance.

Information about a persons/users enrolment will be presented in XML. The following fields will be used:

Field

Type

Length

Description

GUID

Varchar

30

Global Unique Identifier – LDAP_ID

ID Number

Number

Quercus Person ID Number

Repeated list of enrolments

courseCode

Varchar

16

Course Code

instanceCode

Varchar

16

Instance Code

locationCode

Varchar

16

Location Code

locationDescription

Varchar

80

Location Description

courseYear

Number

Course Year

instanceStartDate

Date

Course Instance Start Date

instanceEndDate

Date

Course Instance End Date

credits

Number

Course Instance Credits

academicSession

Number

Academic Session

modeOfStudyCode

Varchar

16

Mode of Study Code

modeOfStudyDescription

Varchar

80

Mode of Study Description

courseStreamCode

Varchar

16

Course Stream Code

courseStreamDescription

Varchar

80

Course Stream Description

quota

Number

Quota

instanceStatusCode

Varchar

16

Course Instance Status Code

instanceStatusDescription

Varchar

80

Course Instance Status Description

studentStatusCode

Varchar

16

Student Status Code

studentStatusDescription

Varchar

80

Student Status Description

studentCategoryCode

Varchar

16

Student Category Code

studentCategoryDescription

Varchar

80

Student Category Description

feeCategoryCode

Varchar

16

Fee Category Code

feeCategoryDescription

Varchar

80

Fee Category Description

feeLevelCode

Varchar

16

Fee Level Code

feeLevelDescription

Varchar

80

Fee Level Description

enrolmentDate

Date

Student Enrolment Date

studentStartDate

Date

Student Start Date

studenEndDate

Date

Student End Date

residentialStatusCode

Varchar

16

Student Residential Status Code

residentialStatusDescription

Varchar

80

Student Residential Status Descrption

The following parameters will be used to obtain information about an enrolment:

Parameter name

Description

Example

userName

The users LDAP username

solar.qll_web.enrolment?username=jbloggs

id

The users quercus id number

solar.qll_web.enrolment?id=123456

guid

The users Global Unique Identifier – often the same as the id number but can be different

solar,qll_web.enrolment?guid=123456_AA01

courseCode

The course code of a course that that the student is enrolled on.

This will return all enrolments for the person on that course

solar.qll_web.enrolment?id=123456&courseCode=’ABCD’

instanceCode

The instance code of a course instance that the student is enrolled on.

This will return a specific enrolment for the person on that course instance

solar.qll_web.enrolment?id=123456&instanceCode=’ABCD_2012’

academicSession

The academic session of the course instances.

This will return all enrolments for the person in a give academic session

solar.qll_web.enrolment? id=123456&academicSession=2012

Note: At least one of following parameters must be past in order to return any data – username, id, guid

If any invalid parameters are passed or if any enrolments are not found the system will return a ‘No Enrolments Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(GUID:ID:Username:courseCode:instanceCode:academicSession:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if GUID, Username, instanceCode and academicSession were null then the following should be hashed:

(:ID::ABCD:::AUTH_KEY)

Information about person notes

The person notes API will return information about a notes associated with a person’s record. Depending on the parameters passed to the API by the calling URL the feed will return either:

All notes associated with a person

All open notes associated with a person

All notes of a particular note type associated with a person

All open notes of a particular note type associated with a person

Information about persons/users notes will be presented in XML. The following fields will be used:

Field

Type

Length

Description

GUID

Varchar

30

Global Unique Identifier – LDAP_ID

ID Number

Number

Quercus Person ID Number

Repeated list of note records

noteTypeCode

Varchar

16

Note Type Code

noteTypeDescription

Varchar

80

Note Type Description

note

Varchar

2000

dateClosed

Date

Date Closed

This data is available from the NOTE table in the Quercus schema.

The following parameters will be used to obtain information about a persons notes

Parameter name

Description

Example

userName

The users LDAP username

solar.qll_web.person_note?username=jbloggs

id

The users quercus id number

solar.qll_web.person_note?id=123456

guid

The users Global Unique Identifier – often the same as the id number but can be different

solar,qll_web.person_note?guid=123456_AA01

current

Flag that indicates whether or not the query returns only open notes or all notes including closed notes.

1 = return only open notes

0 = return all notes including closed notes.

By default all notes will be returned.

solar.qll_web.person_note?id=123456&current=1

noteType

The code of the note type for the note that you want returned

Solar.qll_web.person_note?id=123456&noteTYpe=FINANCE

Note: At least one of following parameters must be past in order to return any data – username, id, guid

If no person notes are found then the system will return a ‘No Person Notes Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(GUID:ID:Username:current:noteType:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if GUID, Username and current were null then the following should be hashed:

(:ID:::noteType:AUTH_KEY)

Information about courses

The Courses API will return information about course instances with the Browse Course service enabled.

Information about courses instances will be presented in XML. The following fields will be used:

Field

Type

Length

Description

Repeated list of course instance records

instanceCode

Varchar

16

Course Instance Code

courseCode

Varchar

16

Course Code

courseDescription

Varchar

80

Course Description

courseYear

Number

Course Year

startDate

Date

Course Instance Start Date

endDate

Date

Course Instance End Date

Session

Number

Academic Session

modeOfStudyCode

Varchar

16

Mode of Study Code

modeOfStudyDescription

Varchar

80

Mode of Study Description

locationCode

Varchar

16

Location Code

locationDescription

Varchar

80

Location Description

streamCode

Varchar

16

Stream Code

streamDescription

Varchar

80

Stream Description

Credits

Number

Course Instance credits

Quota

Number

Course Instance quota

instanceStatusCode

Varchar

Course instance status code

instanceStatusDescription

Varchar

Course Instance status Description

Repeated list of field of study for course instance

fieldOfStudyCode

Varchar

16

Field of Study Code

fieldofStudyDescription

Varchar

80

Field of Study Description

Repeated List of documents associated with a course instance

documentTitle

varchar

200

documentFileName

Varchar

200

URL

Varchar

1000

URL to document

This data is available from the Course, Course Instance and Course Document tables in the Quercus schema.

The following parameters will be used to obtain information about courses

Parameter name

Description

Example

courseCode

The course code of a course

solar.qll_web.courses?courseCode=ABCD

instanceCode

The instanceCode of a course instance

solar.qll_web.courses?instanceCode=ABCD_01

Note: At least one of following parameters must be passed in order to return any data – courseCode or instanceCode

If no courses are found then the system will return a ‘No Courses Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(courseCode:instanceCode:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if courseCode was null then the following should be hashed:

(:instanceCode:AUTH_KEY)

Information about interactions

The interactions API will return information about an applicants existing applications, related course information and the status of the interaction (recorded, submitted, approved etc).

Information about existing interactions will be presented in XML. The following fields will be used:

Field

Type

Length

Description

GUID

Varchar

30

Person LDAP LDAP ID

idNumber

Number

Person ID number

Repeated list of applications

Id

Number

Course Instance Object_id

instanceCode

Varchar

16

Course Instance Code

courseCode

Varchar

16

Course Code

courseDescription

Varchar

80

Course Description

courseYear

Number

Course Year

startDate

Date

Course Instance Start Date

endDate

Date

Course Instance End Date

Session

Number

Academic Session

modeOfStudyCode

Varchar

16

Mode of Study Code

modeOfStudyDescription

Varchar

80

Mode of Study Description

locationCode

Varchar

16

Location Code

locationDescription

Varchar

80

Location Description

streamCode

Varchar

16

Stream Code

streamDescription

Varchar

80

Stream Description

Credits

Number

Course Instance credits

Quota

Number

Course Instance quota

Services applied for

interactionReferenceNo

Number

Application Application Reference

interactionDate

Date

Application Timestamp

interactionStatusCode

Varchar

16

Application Status Code

interactionStatusDescription

Varchar

80

Application Status Description

serviceCode

Varchar

16

Service.Service

serviceDescription

Varchar

80

Service description

serviceLabel

Varchar

80

Service Label

startDate

date

Course Instance Service Start Date

endDate

date

Course Instance Service End Date

url

Varchar

1000

Service URL

Note: the service URL should not be displayed if the interaction is complete. The interaction status should be in ‘RECORDED’ or ‘SAVED’ for the service URL to show

This data is available from the Course, Course Instance, Applicant, Application, Course Instance Service and Service tables.

The following parameters will be used to obtain information about courses:

Parameter name

Description

Example

userName

The users LDAP username

solar.qll_web.interactions?username=jbloggs

id

The users quercus id number

solar.qll_web. interactions?id=123456

guid

The users Global Unique Identifier – often the same as the id number but can be different

solar,qll_web. interactions?guid=123456_AA01

serviceCode

The service code of a service

solar.qll_web. interactions?serviceCode=ONLINE_APP

instanceCode

The instance code of a course instance

solar.qll_web. interactions?instancecode=ABCD

modeOfStudyCode

The mode of study code of a course instance

solar.qll_web. interactions?modeofstudycode=FULL_TIME

locationCode

The location code of a course instance

Solar.qll_web.interactions?locationcode=DUBLIN

statusCode

The status code of a status associated with applications

Solar.qll_web. interactions?statuscode=RECORDED

Note: At least one of following parameters must be past in order to return any data – username, id, guid

If the person is not found then the system will return a ‘No Person Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(username:id:guid:serviceCode:instanceCode:modeOfStudyCode:locationCode:statusCode:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if serviceCode was null then the following should be hashed:

(username:id:guid::instanceCode:statusCode: modeOfStudyCode:locationCode:AUTH_KEY)

Amendments to existing XML feeds

The following feeds will be updated to include course stream, quota and status

qll_web.student

qll_web.common

Information about modules and module instances

The modules API will return information about modules and module instances

Information about modules will be presented in XML. The following fields will be used:

Field

Type

Length

Description

Repeated list of module instance records

moduleInstanceID

Varchar

30

Unique Module Instance ID

moduleCode

Varchar

16

Module Code

moduleTitle

Varchar

80

Module Description

moduleShortname

Varchar

8

Module Short Name

dateApproved

Date

Module Date Approved

dateClosed

Date

Module Date Closed

moduleLevelCode

Varchar

16

Module Level Code

moduleLevelDescription

Varchar

80

Module Level Description

session

Number

Module Instance Academic Session

Credits

Number

Module Instance Credits

Qualification

Varchar

16

Module Instance Qualification Code

statusCode

Varchar

16

Status Code

statusDescription

Varchar

80

Status Description

startDate

Date

Start Date

endDate

Date

End Date

jacsSubjectCode

Varchar

16

JACS Subject Code

jacsSubjectDescription

Varchar

80

JACS Subject Description

ascCode

Varchar

16

ASC Code

ascDescription

Varchar

80

ASC Description

examEntryTyp

Number

1=REGISTER

0=ENTRY

parentCourseCode

Varchar

16

Course Code for parent course

Packaged

Number

1=YES

0=NO

vatRateCode

Varchar

16

VAT Rate Code

vatRateDescription

Varchar

80

VAT Rate Description

Repeated list of module instance assessments

assessmentCode

Varchar

16

Assessment Code

assessmentDescription

Varchar

80

Assessment Description

weightingFactor

Number

Weighting Factor of Assessment

passMark

Number

Pass Mark for Assessment

marksOutOf

Number

Total number of marks available for assessment

Repeated list of module instance departments

deparmentCode

Varchar

16

Department Code

departmentDescription

Varchar

80

Department Description

lectureHours

Number

departmentInput

Number

Repeated list of module instance persons

GUID

varchar

30

Global Unique Identifier

idNumber

Number

firstName

Varchar

30

Person First Name

surname

Varchar

30

Person Surname

personTypeCode

Varchar

16

Person Type Code

personTypeDescription

Varchar

80

Person Type Description

roleStartDate

Date

Start Date

roleEndDate

Date

End Date

The following parameters will be used to obtain information about modules:

Parameter name

Description

Example

moduleCode

The module code of a module

solar.qll_web.modules?moduleCode=ABCD

moduleInstanceID

The unique module instance identifier

solar.qll_web.modules?moduleInstanceID=ABCD_01

Note: At least one of following parameters must be passed in order to return any data – moduleCode or moduleInstanceID

If no modules are found then the system will return a ‘No Modules Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(moduleCode:moduleInstanceID:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if moduleCode was null then the following should be hashed:

(:moduleInstanceID:AUTH_KEY)

Information about course curriculum

The course structure API will return information about modules on a course instance and person roles at level 1 course structure.

Information about the course curriculum will be presented in XML. The following fields will be used:

Field

Type

Length

Description

Repeated list of course instance records

courseInstanceID

Varchar

30

Unique Course Instance ID

courseCode

Varchar

16

Course Code

instanceCode

Varchar

16

Course Instance Code

Session

Number

Academic Session

Repeated List of Level 1 Modules

level1ModuleCode

Varchar

16

Module Code

level1ModuleTypeCode

Varchar

16

Module Type Code

level1ModuleTypeDescription

Varchar

80

Module Type Description

level1Semester

Number

Course Semester

level1Credits

Number

Credits

level1OverallGradeWeighting

Number

Overall Grade Weigting

level1AwardYearSubject

Number

Award Year Subject

TRUE or FALSE

level1QualificationCode

Varchar

16

Qualification Code

Nested repeated list of CPD roles

GUID

Varchar

30

Global Unique Identifier

idNumber

Number

Person ID Number

firstName

Varchar

30

Person First Name

Surname

Varchar

30

Person Surname

Nested Repeated List of Level 2 Modules

level2ModuleCode

Varchar

16

Module Code

level2ModuleTypeCode

Varchar

16

Module Type Code

level2ModuleTypeDescription

Varchar

80

Module Type Description

level2Semester

Number

Course Semester

level2Credits

Number

Credits

level2OverallGradeWeighting

Number

Overall Grade Weigting

Nested repeated list of level 3 modules

level3ModuleCode

Varchar

16

Module Code

level3ModuleTypeCode

Varchar

16

Module Type Code

level3ModuleTypeDescription

Varchar

80

Module Type Description

level3Semester

Number

Course Semester

level3Credits

Number

Credits

level3OverallGradeWeighting

Number

Overall Grade Weigting

The following parameters will be used to obtain information about a course structure

Parameter name

Description

Example

courseInstanceID *

The unique course instance identifier

solar.qll_web.course_structure?courseInstanceID=ABCD_12

instanceCode *

The course instance code

solar.qll_web.course_structure?instanceCode=ABCDEF

session

The course instance academic session

solar.qll_web.course_structure?courseInstanceID=ABCD_12&session=2013

courseCode

The course Code

Solar.qll_web.course_structure?instanceCode=ABCDEF&courseCode=AB

Note: At least one of following parameters must be passed in order to return any data – courseInstanceID or instanceCode

If no course instances are found then the system will return a ‘No Instances Found’ response.

If no course structure is found then the system will return a ‘No data found’ reponse

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(courseInstanceID:InstanceCode:session:courseCode:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if courseCode was null then the following should be hashed:

(courseInstanceID:InstanceCode:session::AUTH_KEY)

Information about student curriculum

The student curriculum API will return information about a student’s curriculum.

Information about the student curriculum will be presented in XML. The following fields will be used:

Field

Type

Length

Description

GUID

Varchar

30

Global Unique Identifier

idNumber

Number

Person ID Number

Repeated list of course instance records

courseInstanceID

Varchar

30

Unique Course Instance ID

courseCode

Varchar

16

Course Code

instanceCode

Varchar

16

Course Instance Code

Session

Number

Academic Session

Repeated list of level 1 modules

level1ModuleInstanceID

Varchar

30

Unique Module Instance ID

level1ModuleCode

Varchar

16

Module Code

level1ModuleTypeCode

Varchar

16

Module Type Code

level1ModuleTypeDescription

Varchar

80

Module Type Description

level1ModuleStartDate

Date

Module Instance Start Date

level1ModuleEndDate

Date

Module Instance End Date

level1ModuleCredits

Number

Credits

level1Semester

Number

Course Semester

level1SubjectRegStatus

Varchar

16

Subject Registration Status Code

level1SubjectRegStatusDescription

Varchar

80

Subject Registration Status Description

Nested repeated list of level 2 modules

level2ModuleInstanceID

Varchar

30

Unique Module Instance ID

level2ModuleCode

Varchar

16

Module Code

level2ModuleTypeCode

Varchar

16

Module Type Code

level2ModuleTypeDescription

Varchar

80

Module Type Description

level2ModuleStartDate

Date

Module Instance Start Date

level2ModuleEndDate

Date

Module Instance End Date

level2ModuleCredits

Number

Credits

level2Semester

Number

Course Semester

level2SubjectRegStatus

Varchar

16

Subject Registration Status Code

level2SubjectRegStatusDescription

Varchar

80

Subject Registration Status Description

Nested repeated list of level 3 modules

level3ModuleInstanceID

Varchar

30

Unique Module Instance ID

level3ModuleCode

Varchar

16

Module Code

level3ModuleTypeCode

Varchar

16

Module Type Code

level3ModuleTypeDescription

Varchar

80

Module Type Description

level3ModuleStartDate

Date

Module Instance Start Date

level3ModuleEndDate

Date

Module Instance End Date

level3ModuleCredits

Number

Credits

level3Semester

Number

Course Semester

level3SubjectRegStatus

Varchar

16

Subject Registration Status Code

level3SubjectRegStatusDescription

Varchar

80

Subject Registration Status Description

The following parameters will be used to obtain information about a student’s curriculum:

Parameter name

Description

Example

userName

The users LDAP username

solar.qll_web.curriculum?username=jbloggs

id

The users quercus id number

solar.qll_web.curriculum?id=123456

guid

The users Global Unique Identifier – often the same as the id number but can be different

solar,qll_web.curriculum?guid=123456_AA01

courseCode

The course code of a course that that the student is enrolled on.

This will return all curriculum records for the person on that course

solar.qll_web.curriculum?id=123456&courseCode=’ABCD’

instanceCode

The instance code of a course instance that the student is enrolled on.

This will return the curriculum records for the specific course instance code.

solar.qll_web.curriculum?id=123456&instanceCode=’ABCD_2012’

session

The academic session of the course instances.

This will return all curriculum records for the student in a given academic session

solar.qll_web.curriculum? id=123456&session=2012

courseInstanceID

The unique course instance ID. This will return the curriculum records for the specific course instance

solar.qll_web.curriculum? id=123&courseInstanceID=ABCD_125

Note: At least one of following parameters must be past in order to return any data – username, id, guid

If any invalid parameters are passed or if any enrolments are not found the system will return a ‘No Curriculum Records Found’ response.

Security

If security is enabled the following parameters must be hashed using the specified hashing algorithm (MD5 or SHA1)

(GUID:ID:Username:courseCode:instanceCode:session:courseInstanceID:AUTH_KEY)

The colons should be hashed and if any parameter is null it should be included anyway, for example if GUID, Username, instanceCode and academicSession were null then the following should be hashed:

(:ID::ABCD::::AUTH_KEY)