README
xAPI - IMS Caliper utility
The xAPI - IMS Caliper utility converts learning activities into xAPI and IMS Caliper compatible statements. Using an easy-to-use API, it aims to abstract away the details of these specifications and ensures a consistent use of statement vocabulary across applications.
Installation
The xAPI - IMS Caliper utility can be included in your project through npm:
npm install xapicaliper
The utility can then be pulled into a file using:
var xapicaliper = require('xapicaliper');
Usage
The xAPI - IMS Caliper utility provides a separate transformation function for each type of activity. However, all of these functions have the same signature:
xapicaliper.<domain>.<type>(config, statement, callback);
config
The config object can have the following properties:
type
(optional): The type of learning activity statement to generate. One ofxapicaliper.CONSTANTS.TYPE.XAPI
orxapicaliper.CONSTANTS.TYPE.CALIPER
. Defaults to xAPIplatform
(required): The information about the platform generating learning activitiesplatform.url
(required): The URL of the platform generating learning activitiesplatform.name
(required): The name of the platform generating learning activitiesplatform.description
(optional): The description of the platform generating learning activities
lrs
(optional): The LRS configuration values. This should only be provided when this utility should also store the generated xAPI or Caliper statement in a Learning Record Storelrs.endpoint
(optional): The URL to the endpoint used for storing new xAPI or Caliper statementslrs.username
(optional): The LRS usernamelrs.password
(optional): The LRS password
An example config object could look like this:
{
'type': xapicaliper.CONSTANTS.TYPE.CALIPER, // A Caliper statement will be generated
'platform': {
'url': 'https://bcourses.berkeley.edu/',
'name': 'bCourses',
'description': 'The UC Berkeley LMS'
},
'lrs': { // Leave this empty to not automatically store the generated statement in an LRS
'endpoint': 'https://foo.bar/statements', // The REST endpoint to post the generated statement to
'username': 'POoHJjcbl',
'password': 'kIRiY7v'
}
}
statement
The statement object contains the information about the learning activity and always contains the following properties:
timestamp
(optional): The time at which the learning activity took place. Defaults to the current timeactor
(required): The user performing the action described by the learning activityactor.id
(required): The URL of the user accountactor.id_source
(required): The canonical home page for the system the user's account is on.openid
when an OpenId user id has been providedactor.name
(optional): The display name of the useractor.email
(optional): The email address of the user. This can also be an SHA1 sum of the email address in case the email address needs to be hashed before it can be usedactor.created
(optional): The date at which the user was createdactor.updated
(optional): The date at which the user was last updated
context
(optional): Object that describes the context in which a learning activity took place (e.g., course)context.id
(required): The URL of the contextcontext.name
(required): The name of the context (e.g., course name)context.description
(required): The description of the context (e.g., course description)
metadata
(required): The metadata that describes the learning activity. Every type of learning activity requires a different set of metadata
An example statement object could look like this:
{
'timestamp': '2016-01-01T05:23:42.000Z',
'actor': {
'id': 'http://berkeley.edu/directory/1234',
'id_source': 'http://berkeley.edu/directory',
'name': 'Nicolaas Matthijs',
'email': 'nicolaas@foo.com',
'created': '2014-03-01T01:28:12.000Z'
},
'context': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111',
'name': 'Biology 101',
'description': 'Introductory course in Biology'
},
'metadata': {} // As defined by learning activity type
}
callback
The callback function is a standard callback function that is executed when the learning activity statement has been generated and stored in the configured Learning Record Store, if any.
It can be used in the following way:
xapicaliper.<domain>.<type>(config, statement, function(err, statement) {
if (err) {
// An error occured while generating or storing the statement
}
// Print the generated learning activity statement
console.log(statement);
});
Learning Activities
The xAPI - Caliper utility currently supports the following learning activies:
Session Activities
Login
xapicaliper.session.login(config, statement, callback)
A learning activity where a user logs in to a system.
The following metadata properties can be provided:
id
(required): The URL of the session generated by logging in
An example could look like this:
xapicaliper.session.login({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/sessions/6cc96b98-6968-4cc4-aa98-6b6d94606970'
}
}, function() { <see callback> });
Logout
xapicaliper.session.logout(config, statement, callback)
A learning activity where a user logs out of a system.
xapicaliper.session.login({ <see config> }, {
<see statement>,
'metadata': {},
}, function() { <see callback> });
Navigate to course
xapicaliper.session.navigateToCourse(config, statement, callback)
A learning activity where a user logs in to a system.
The following metadata properties can be provided:
id
(required): The URL of the coursename
(required): The name of the coursedescription
(optional): The description of the course
An example could look like this:
xapicaliper.session.navigateToCourse({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111',
'name': 'Biology 101',
'description': 'Introductory course in Biology'
}
}, function() { <see callback> });
Navigate to page
xapicaliper.session.navigateToPage(config, statement, callback)
A learning activity where a user navigates to a page.
The following metadata properties can be provided:
id
(required): The URL of the pagename
(optional): The name of the page
An example could look like this:
xapicaliper.session.navigateToPage({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments',
'name': 'Assignments Tool'
}
}, function() { <see callback> });
Course Activities
Create course
xapicaliper.course.create(config, statement, callback)
A learning activity where a user creates a new course.
The following metadata properties can be provided:
id
(required): The URL of the coursename
(required): The name of the coursedescription
(optional): The description of the coursestart
(optional): The time at which the course startsend
(optional): The time at which the course ends
An example could look like this:
xapicaliper.course.create({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111',
'name': 'Biology 101',
'description': 'Introductory course in Biology',
'start': '2014-03-01T01:28:12.000Z',
'end': '2014-06-01T23:59:59.000Z'
}
}, function() { <see callback> });
Enroll course
xapicaliper.course.enroll(config, statement, callback)
A learning activity where a user enrolls in a course.
The following metadata properties can be provided:
course
(required): The URL of the course in which the student enrolls
An example could look like this:
xapicaliper.course.enroll({ <see config> }, {
<see statement>,
'metadata': {
'course': 'https://bcourses.berkeley.edu/api/v1/courses/111'
}
}, function() { <see callback> });
Leave course
xapicaliper.course.leave(config, statement, callback)
A learning activity where a user leaves a course.
The following metadata properties can be provided:
course
(required): The URL of the course the student leaves
An example could look like this:
xapicaliper.course.leave({ <see config> }, {
<see statement>,
'metadata': {
'course': 'https://bcourses.berkeley.edu/api/v1/courses/111'
}
}, function() { <see callback> });
Assignment Activities
Create assignment
xapicaliper.assignment.create(config, statement, callback)
A learning activity where a user creates a new assignment.
The following metadata properties can be provided:
id
(required): The URL of the assignmenttitle
(required): The title of the assignmentdescription
(optional): The description of the assignmentdue_at
(optional): The due date of the assignmentmax_points
(optional): The maximum number of points for the assignmentsubmission_types
(optional): An array of accepted submission types for the assignment entry
An example could look like this:
xapicaliper.assignment.create({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333',
'title': 'Farm Animals Midterm',
'description': 'The midterm on Farm Animals in Medieval England',
'due_at': '2014-03-01T01:28:12.000Z',
'max_points': 50,
'submission_types': ['online_quiz', 'online_upload']
}
}, function() { <see callback> });
View assignment
xapicaliper.assignment.view(config, statement, callback)
A learning activity where a user views an assignment.
The following metadata properties can be provided:
assignment
(required): The URL of the assignment that was viewed
An example could look like this:
xapicaliper.assignment.view({ <see config> }, {
<see statement>,
'metadata': {
'assignment': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333',
}
}, function() { <see callback> });
Submit assignment
xapicaliper.assignment.submit(config, statement, callback)
A learning activity where a user submits an assignment submission.
The following metadata properties can be provided:
id
(required): The URL of the assignment submissionassignment
(required): The URL of the assignment for the submissionsubmission
(optional): The content of the assignment submission. This can be a text response or a link to the response
An example could look like this:
xapicaliper.assignment.submit({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333/submissions/987',
'assignment': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333',
'submission': 'https://bcourses.berkeley.edu/api/v1/courses/111/files/444/download'
}
}, function() { <see callback> });
Grade assignment
xapicaliper.assignment.grade(config, statement, callback)
A learning activity where a user grades an assignment submission.
The following metadata properties can be provided:
id
(required): The URL of the assignment submission that is gradedgrade
(required): The grade for the assignment submissiongrade_min
(optional): The minimum possible grade for the assignmentgrade_max
(optional): The maximum possible grade for the assignment
An example could look like this:
xapicaliper.assignment.submit({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333/submissions/987',
'grade': 45,
'grade_min': 0,
'grade_max': 50
}
}, function() { <see callback> });
Assignment feedback
xapicaliper.assignment.feedback(config, statement, callback)
A learning activity where a user provides feedback on an assignment submission.
The following metadata properties can be provided:
id
(required): The URL of the assignment submission feedbacksubmission
(required): The URL of the assignment submission for the feedbackfeedback
(required): The feedback provided on the assignment submission
An example could look like this:
xapicaliper.assignment.feedback({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333/submissions/987/feedback/579',
'submission': 'https://bcourses.berkeley.edu/api/v1/courses/111/assignments/333/submissions/987',
'feedback': 'Excellent work!'
}
}, function() { <see callback> });
Discussion Activities
Start discussion
xapicaliper.discussion.start(config, statement, callback)
A learning activity where a user starts a new discussion.
The following metadata properties can be provided:
id
(required): The URL of the discussiontitle
(required): The title of the discussionbody
(optional): The body of the discussion
An example could look like this:
xapicaliper.discussion.start({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/discussions/222',
'title': 'Farm Animals Discussion',
'body': 'An informative discussion about your favourite farm animal'
}
}, function() { <see callback> });
Read discussion
xapicaliper.discussion.read(config, statement, callback)
A learning activity where a user reads a discussion.
The following metadata properties can be provided:
discussion
(required): The URL of the discussion that was read
An example could look like this:
xapicaliper.discussion.read({ <see config> }, {
<see statement>,
'metadata': {
'discussion': 'https://bcourses.berkeley.edu/api/v1/courses/111/discussions/222'
}
}, function() { <see callback> });
Post to discussion
xapicaliper.discussion.post(config, statement, callback)
A learning activity where a user posts to a discussion.
The following metadata properties can be provided:
id
(required): The URL of the discussion entry that was postedbody
(required): The body of the discussion entrydiscussion
(required): The URL of the discussion the discussion entry is made inparent
(optional): The URL of the discussion entry to which this discussion entry is a reply
An example could look like this:
xapicaliper.discussion.post({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/discussions/222/entries/456',
'body': 'I love chickens',
'discussion': 'https://bcourses.berkeley.edu/api/v1/courses/111/discussions/222',
'parent': 'https://bcourses.berkeley.edu/api/v1/courses/111/discussions/222/entries/123'
}
}, function() { <see callback> });
File Activities
Upload file
xapicaliper.file.upload(config, statement, callback)
A learning activity where a user uploads a new file.
The following metadata properties can be provided:
id
(required): The URL of the file that was uploadedtitle
(required): The title of the filedescription
(optional): The description of the fileurl
(optional): The URL at which the file can be downloadedsize
(optional): The size of the file in bytesmime_type
(optional): The mime type of the file
An example could look like this:
xapicaliper.file.upload({ <see config> }, {
<see statement>,
'metadata': {
'id': 'https://bcourses.berkeley.edu/api/v1/courses/111/files/444',
'title': 'Syllabus 101.pdf',
'description': 'The syllabus for Biology 101',
'url': 'https://bcourses.berkeley.edu/api/v1/courses/111/files/444/download',
'size': 1234,
'mime_type': 'application/pdf'
}
}, function() { <see callback> });
Preview file
xapicaliper.file.preview(config, statement, callback)
A learning activity where a user previews a file.
The following metadata properties can be provided:
file
(required): The URL of the file that was downloaded
An example could look like this:
xapicaliper.file.preview({ <see config> }, {
<see statement>,
'metadata': {
'file': 'https://bcourses.berkeley.edu/api/v1/courses/111/files/444'
}
}, function() { <see callback> });
Download file
xapicaliper.file.download(config, statement, callback)
A learning activity where a user downloads a file.
The following metadata properties can be provided:
file
(required): The URL of the file that was downloaded
An example could look like this:
xapicaliper.file.download({ <see config> }, {
<see statement>,
'metadata': {
'file': 'https://bcourses.berkeley.edu/api/v1/courses/111/files/444'
}
}, function() { <see callback> });