Course instance configuration¶

NOTE: Any time you edit or add an infoCourseInstance.json file on a local copy of PrairieLearn, you need to click the “Load from disk” button in the page header so that the local PrairieLearn server reloads the changes.

Directory layout¶

A course instance corresponds to a single offering of a course, such as "Fall 2016", or possibly "Fall 2016, Section 1". A course instance like Fa16 is contained in one directory and has a configuration file (infoCourseInstance.json) and a subdirectory (assessments) containing a list of assessments. The assessments directory should always exist, but may be empty if no assessments have been added. A course instance may be located in the root courseInstances directory, or any subfolder that is not a courseInstance itself.

exampleCourse
`-- courseInstances
    +-- Fa16                          # Fall 2016 course instance
    |   +-- infoCourseInstance.json   # configuration file (see below)
    |   +-- assessments
    |   |   +-- hw01                  # first homework for Fa16
    |   |   |   `-- ...               # files for Homework 1
    |   |   `-- hw02                  # second homework for Fa16
    |   |       `-- ...               # files for Homework 2
    |   +-- clientFilesCourseInstance # (1)!
    |   |   `-- Fa16_rules.pdf        # files for Fall 2016
    `-- Sp17
        +-- infoCourseInstance.json   # Spring 2017 configuration
        +-- assessments
        |   `-- ...                   # Spring 2017 assessments
        +-- clientFilesCourseInstance # (2)!
        |   `-- ...                   # files for Spring 2017

See clientFiles and serverFiles for information on the clientFilesCourseInstance directory.
See clientFiles and serverFiles for information on the clientFilesCourseInstance directory.

See an example courseInstances directory in the PrairieLearn example course.

`infoCourseInstance.json`¶

This file specifies basic information about the course instance:

infoCourseInstance.json

{
  "uuid": "62fbe2a4-8c22-471a-98fe-19e5d5da1bbe",
  "longName": "Spring 2015",
  "allowAccess": [
    {
      "startDate": "2015-01-19T00:00:01",
      "endDate": "2015-05-13T23:59:59"
    }
  ]
}

See the reference for infoCourseInstance.json for more information about what can be added to this file.

Access controls¶

The course instance allowAccess rules determine who can access the course instance and when they can do so. Course staff always have access. The simple example below gives students access between the start (Jan 19th) and end (May 13th) of the semester, as follows.

infoCourseInstance.json

{
  "allowAccess": [
    {
      "startDate": "2015-01-19T00:00:01",
      "endDate": "2015-05-13T23:59:59"
    }
  ]
}

See the access control documentation for more details on allowAccess rules.

Controlling access by institution¶

By default, only students that belong to the course's institution can access the course instance. You can use the institution property to allow access from other institutions. For instance, you can use the following rule to allow students from any institution to access the course instance between the specified dates:

infoCourseInstance.json

{
  "allowAccess": [
    {
      "startDate": "2015-01-19T00:00:01",
      "endDate": "2015-05-13T23:59:59",
      "institution": "Any"
    }
  ]
}

Controlling access by UID¶

You can restrict access to particular students by listing their UIDs in the uids property. For instance, the following rule only allows student1@example.com and student2@example.com to access the course instance between the specified dates:

infoCourseInstance.json

{
  "allowAccess": [
    {
      "startDate": "2015-01-19T00:00:01",
      "endDate": "2015-05-13T23:59:59",
      "uids": ["student1@example.com", "student2@example.com"]
    }
  ]
}

Enrollment controls¶

Students can enroll in a course instance through one of two ways:

They can use a URL specific to the course instance or to one of its assessments. You can find the "student link" on the "Settings" tab of the course instance. This link points students to the list of assessments associated to the course instance, enrolling them automatically in the course instance if they are not yet enrolled.
They can use the "Add or remove courses" button on PrairieLearn's homepage. This button opens a page listing all course instances that are currently available for enrollment, giving students the option to add new courses.

Some instructors may wish to hide their course from the list of available course instances. This may be done to provide a small level of control over which students get access to the course, or to avoid confusion in case of course instances that are not expected to be visible to students in general. For these instances, the following setting will hide the course instance from the list of instances on the add/remove courses page, even if the instance is available for enrollment.

infoCourseInstance.json

{
  "hideInEnrollPage": true
}

Note that this is not a security setting. Students may still enroll in the course instance if they get access to the URL, such as from a friend. Instructors that wish to actually restrict course enrollment to a specific list of students should instead use an access rule with an explicit list of UIDs, as described under "Controlling access by UID".

Assessment page organization¶

Instructors can group assessments by course modules (topics, sections, or chapters in a course) or by assessment sets (homeworks, quizzes, exams, and so on). By default, all assessments in a course instance are grouped by "Set". Setting the property "groupAssessmentsBy" to "Module" will group assessments together by module on the student assessments overview page.

infoCourseInstance.json

{
  "groupAssessmentsBy": "Module"
}

For more information about assessment modules, see Course configuration.

Timezone¶

The default timezone for course instances is the timezone of the course. This can be changed with the timezone property in infoCourseInstance.json. For example:

infoCourseInstance.json

{
  "timezone": "America/New_York"
}

Allowable timezones are those in the TZ column in the list of tz database time zones, which is a display version of the IANA Time Zone Database.

LTI support¶

Warning

LTI 1.1 support as described below is deprecated. We recommend using LTI 1.3 for all new course instances. See the LTI 1.3 documentation for more details.

LTI Overview¶

LTI, or Learning Tools Interoperability, is the ability for Learning Management Systems (LMSes) to link together. In our context, it means that sites like Coursera can link into assessments in PrairieLearn, give the student a PrairieLearn experience, and report the assessment score back to Coursera automatically.

PrairieLearn LTI support enables a new authentication source (that creates the user in PL and enrolls them in the appropriate course instance) with a grade reporting functionality. Everything else (course instance, assessment and question configuration and workflows) are the same. Assessment access control rules still apply for LTI linked assessments.

Enabling LTI support in a course instance¶

To point an LMS to use PrairieLearn LTI, you must first create a private LTI credential inside PrairieLearn. These credentials are then configured inside the LMS to connect to PrairieLearn.

To create or manage LTI credentials for a course instance, instructors can visit the Admin / LTI page in the course instance.

An LTI credential consists of 3 parts:

Launch URL - the URL to configure the LMS to link into PrairieLearn
Consumer key - a unique identifier for the LMS context
Shared secret - a password for the consumer key

A single LMS course should use the same credential. If multiple courses need to link into the course instance, multiple LTI credentials can be created.

PrairieLearn logins via LTI are unique to their LMS course. For example, if an Illinois student is taking a Coursera LTI course they will have two different user accounts in PrairieLearn.

It is also necessary to add an accessRule in infoCourseInstance.json with "institution": "LTI". See Access control for more details.

LTI linking into an assessment¶

LTI supports the concept of "deep linking", such that an assignment link inside the originating LMS can be followed directly into a specific assessment in PrairieLearn. For score reporting back to the LMS, PrairieLearn requires this linking. If a student follows an LTI link from the LMS that has not been configured yet in PrairieLearn, they will receive an error message.

The first time an instructor (in the LMS context) follows a newly created LTI PrairieLearn link, they will be delivered to the Admin / LTI page. The LTI link targets section of the page will be populated with the new link information, and the PL course instance's assessments will be listed as a dropdown. These can also be edited at any time from the Admin / LTI page.

A course can use the same LTI credential to create multiple links to PrairieLearn, but each link must be configured in PL to an assessment. Multiple links can be created to the same assessment.

Score reporting back to the LMS (LTI outcomes)¶

If the LTI link inside the LMS was configured to connect to the LMS gradebook then PrairieLearn scores will also be shown and updated in the LMS. This requires the student to have followed the link from the LMS into PrairieLearn when working on the assessment. LTI does not give PrairieLearn a way to update a score in the LMS gradebook for anything other than a linked assignment. i.e. PrairieLearn can't push other scores into the LMS; the request must originate from the LMS.

Scores are still shown to students and instructors in the normal places in PrairieLearn. The LTI outcomes functionality adds additional reporting back to the originating LMS.

Once the student's assessment instance is linked back to an LMS gradebook entry, any scoring activity on PrairieLearn will be reported back to the LMS. That includes students clicking grade, external grading systems reporting back to PrairieLearn, or instructors manually adjusting grades inside PrairieLearn. These grade updates can happen asynchronously and independently of the student interacting with PrairieLearn.

Course instance configuration¶

Directory layout¶

infoCourseInstance.json¶

Access controls¶

Controlling access by institution¶

Controlling access by UID¶

Enrollment controls¶

Assessment page organization¶

Timezone¶

LTI support¶

LTI Overview¶

Enabling LTI support in a course instance¶

LTI linking into an assessment¶

Score reporting back to the LMS (LTI outcomes)¶

`infoCourseInstance.json`¶