Course and Class Provisioning

To create a course online, instead of using our API, go to: https://www.openlearning.com/courses/create/

Provision a New Course

API Method (POST, GET):

https://www.openlearning.com/api/provision/course/<New Course Path>

POST parameters:

title A string containing the course title (e.g. "How to Draw Horses")
category A category which this course may belong to (e.g. "Art")

e.g.

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/provision/course/${NEW_COURSE_PATH}" -d "title=How to Draw Horses" -d "category=Art"

This will return a JSON object which looks like:

{
   "success": true,
   "path": "courses/myNewCourse",
   "url": "https://www.openlearning.com/courses/myNewCourse"
}

Provision a New Class within an Existing Course

API Method (POST, GET):

https://www.openlearning.com/api/provision/class/<Existing Course Path>

POST parameters:

title A string containing the class title (e.g. "First Semester")
type

Either:

"open" - anyone can join this class

"requires-activation-code" - only those with an activation code may enrol

"invite-only" - only those invited to join may enrol

"closed" - no-one can join this class yet

isBilled "true" or "false" - depending on whether students need to pay for this class
studentPrice A number, e.g. "12.00" which is the price to charge students
currency e.g. "USD" or "AUD"
activationCode A code which users need in order to join the class e.g. "My Secret Code"
startDate When this class starts, an ISO 8601 date/time string.

e.g.

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/provision/class/${COURSE_PATH}" -d "title=First Class" -d "type=open"

This will return a JSON object which looks like:

{
   "success": true,
   "class": {
      "path": "courses/myCourse/Cohorts/FirstClass",
      "title": "First Class",
      "type": "open"
   }
}

Course/Class Setup

 

Change the Online/Offline Status of a Course

API Method (POST, GET):

https://www.openlearning.com/api/course/status/<Course Path>

POST parameters:

status=online

or

status=offline

e.g. to take a course offline:

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/course/status/${COURSE_PATH}" -d "status=offline"

This will return:

{
    "success": true,
    "status": "offline"
}

List course administrators

API Method (GET):

https://www.openlearning.com/api/course/admins/<Course Path>

e.g. to list course admins:

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/course/admins/${COURSE_PATH}"

This will return:

{
    "admins": [
        "example1@email.com",
        "example2@email.com"
    ],
    "success": true
}

Add a course administrator

API Method (POST):

https://www.openlearning.com/api/course/admins/<Course Path>

POST parameters:

email_address A string that represents the email address of the user account that will become an administrator for the Course.

e.g. to add a course admin:

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/course/admins/${COURSE_PATH}" -d "email_address=example3@email.com"

This will return:

{
    "success": true
}

Change properties of a Class

API Method (POST, GET):

https://www.openlearning.com/api/class/<Class Path>

POST parameters:

title A string containing the class title (e.g. "First Semester")
type

Either:

"open" - anyone can join this class

"requires-activation-code" - only those with an activation code may enrol

"invite-only" - only those invited to join may enrol

"closed" - no-one can join this class yet

isBilled "true" or "false" - depending on whether students need to pay for this class
studentPrice A number, e.g. "12.00" which is the price to charge students
currency e.g. "USD" or "AUD"
activationCode A code which users need in order to join the class e.g. "My Secret Code"
startDate When this class starts, an ISO 8601 date/time string.

e.g.

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/class/${CLASS_PATH}" -d "title=First Class" -d "type=open"

This will return a JSON object which looks like:

{
   "success": true,
   "class": {
      "path": "courses/myCourse/Cohorts/FirstClass",
      "title": "First Class",
      "type": "open"
   }
}

List Classes in a Course

API Method (GET):

https://www.openlearning.com/api/course/classes/<Course Path>

This will return:

{
    "classes": [
        {
            "path": "courses/myCourse/Cohorts/FirstClass",
            "title": "First Class",
            "url": "https://www.openlearning.com/courses/myCourse/Cohorts/FirstClass"
        }
    ],
    "success": true
}

List Students in an Institution Portal

API Method (GET):

https://www.openlearning.com/api/institution/enrolments

GET parameters:

institution - Relative path to institution portal (e.g. myInstitute)

start - The starting position of the list of enrolments. (optional and defaults to 0)

end - The end position of the list of enrolments. (optional and defaults to 50)

search - text to search for a users name or group. (optional and defaults to return all enrolments)

e.g.

curl -XGET -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/enrolments?institution=myInstitute"


List A Students Enrolments in an Institution Portal

API Method (GET):

https://www.openlearning.com/api/institution/myCourses

GET parameters:

institution - Relative path to institution portal (e.g. myInstitute)

e.g.

curl -XGET -u "${STUDENT_USERNAME}:${STUDENT_PASSWORD}" "https://www.openlearning.com/api/institution/myCourses?institution=myInstitute"

This will return:

{
    "courses": [
        {
            "name": "course name",
            "isOpen": "open",
            "url": "https://www.openlearning.com/myInstitute/courses/courseCode",
            "isEnrolledIn": true,
            "progress": 50, # percentage completed, 0 if isEnrolledIn is false.
            "path": "myInstitute/courses/courseCode",
            "promoImage": "URL" # URL of the promo image
        }
    ],
    "success": true
}

Invite Students into an Institution Portal

API Method (POST):

https://www.openlearning.com/api/institution/invite

POST parameters:

institution - Relative path to institution portal (e.g. myInstitute)

emailAddressList - A new-line separated list of email addresses. You can specify the user's full name when creating the account (see generateAccount parameter), by placing them after the email address separated by a comma (e.g. Email Address, Full Name). The user can also be added to any institution groups by placing comma separated group names after the Full Name (e.g. Email Address, Full Name, Group 1, Group 2).

generateAccount - true or false flag to specify that a user account will be automatically created and a random password sent to the invited email address. Only institutions with this feature enabled will be able to use this option, otherwise it will ignore this option.

enrollCohorts - A JSON encoded Array of cohort paths that the students will be enrolled in.

This will return:

{
    "success": True,

    # autoEnrolledStudents represents accounts that already existed, and have been added to the institution
    "autoEnrolledStudents": [{
        "email": "nowenrolled@student.com",
        "user": { ... } # user data
    }],

    # alreadyEnrolledStudents represents accounts that have already been invited to the institution
    "alreadyEnrolledStudents": [{
        "email": "enrolled@student.com",
        "user": { ... } # user data
    }],
    
    # pendingEnrolledEmails are invited, but have not joined the institution yet. The student will need to verify their email address first.
    # If generateAccount is true, then these emails now represent new users that have been created.
    "pendingEnrolledEmails": ["myemail@example.com"],

    # skipped due to being invalid
    "unprocessedEmails": ["bademail.com"],
}

e.g.

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com"

e.g. with generateAccount and full name

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com,Foo Bar" -d "generateAccount=true"

e.g. with generateAccount, full name, and 2 group names

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com,Foo Bar,A Group,Group 1" -d "generateAccount=true"

e.g. with enrollCohorts

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com" -d 'enrollCohorts=["myInstitute/courses/courseA/cohorts/CohortA","myInstitute/courses/courseB/cohorts/CohortB"]'


Import Student Information for an Institution Portal

API Method (POST):

https://www.openlearning.com/api/institution/importInformation

POST parameters:

institution - Relative path to institution portal (e.g. myInstitute)

emailAddressList - A new-line separated list of email addresses. You can specify extra info by placing them after the email address separated by commas (e.g. Email Address, Identifier, Username)

e.g.

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/importInformation" -d "institution=myInstitute"& -d "emailAddressList=myemail@example.com"


Invite Students into a Class

API Method (POST):

https://www.openlearning.com/api/class/invite/<Class Path>

POST parameters:

emailAddressList - A new-line separated list of email addresses

e.g.

curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/class/invite/${CLASS_PATH}" -d "emailAddressList=myemail@example.com"


Sign into OpenLearning from an External Service

via LTI:

OpenLearning accepts LTI authentication (as a POST request) at the following endpoint:

https://www.openlearning.com/lti/<launch path>

Request an LTI connection be set up for your institution, or course (email support at openlearning.com).

 

via a URL (link):

https://www.openlearning.com/courseLogin/<Course Path>?signed_request=<Authentication Code>

To generate an authentication code:

  1. Request an Institution Shared Secret from OpenLearning (email support at openlearning.com). Do not reveal this secret publicly.
  2. Create a payload of JSON data containing: {"issued_at": 1402643065, "user_id": "user@example.com", "full_name": "Jayne Doe"} (where issued_at is seconds since unix epoch)
  3. Create an encoded payload by base-64 encoding the JSON data string (this may also use URL-safe encoding which substitutes - instead of + and _ instead of /)
  4. Generate a SHA-256 HMAC digest of the payload data string and the provided Shared Secret
  5. Create an encoded signature by base-64 encoding the HMAC digest
  6. Join the encoded signature and the encoded payload with a . (period/full-stop) character

This will allow the generated (private) link to log the specified user into OpenLearning provided all of the following are satisfied:

  • The user is already enrolled in the course specified, or the specified email address has been invited to join the course (a new account will be created and the user will be enrolled into this course)
  • The user's account is managed by your institution (an existing matching account does not already exist that has had prior activity on OpenLearning)
  • The issued_at time is less than a day old

 

Note: padding ('=' characters) at the end of base64 encoded data are optional and may be omitted.

You can test your HMAC implementation against a reference at (never reveal your actual shared secret):

https://www.openlearning.com/api/login/referenceHMAC/?payload=<JSON Data>&secret=<Secret>

(by default this uses url-safe base64 encoding, optionally an encoding=base64 parameter can be passed to use standard base64 encoding)

You can also test that your implementation will authenticate at:

https://www.openlearning.com/api/login/testHMAC/?signed_request=<Signed Request>&secret=<Secret>

(again never reveal your actual secret)

 

The following is an implementation in Python:

import hmac, hashlib 
import time
import base64
import json
def generate_signed_request(shared_secret, user_id, full_name):
    payload = {"issued_at": int(time.time()), "user_id": user_id, "full_name": full_name}
    encoded_payload = base64.urlsafe_b64encode(json.dumps(payload))
    hmac_signature = hmac.new(shared_secret, encoded_payload, hashlib.sha256).digest()
    encoded_signature = base64.urlsafe_b64encode(hmac_signature)
    signed_request = encoded_signature + '.' + encoded_payload
    return signed_request 

 

  Comments