Courses - Data Structures

Owned by (OLD ACCOUNT) Erin Nettifee
Last updated: Sep 02, 2021
4 min read

Various JSON schemas for Courses can be found in Gitlab here: https://github.com/folio-org/mod-courses/tree/master/ramls. This information is most relevant if you are planning to import course data from another system, or if you are planning to use / write reports that use the underlying JSON information from the courses app.

How courses are stored in underlying data, and how cross-listed courses are linked together

A course viewed in FOLIO actually consists of two pieces, a course, and a courselisting.

A course object stores the information from the bottom part of the created course - in Basic course information



A courselisting stores the information from the bottom part of the created course in the Course listing information 

Once a course is created and saved, you can then edit the course to add an instructor, which is stored as its own object (instructor.json) which is linked to the courselisting. You also have other associated data pieces that are configured in settings and linked to either the course or courselisting - department, course type, term and location. (Note that locations are configured in Inventory settings, not Courses settings.)

So, what does all of this mean?

  • In the UI, what you think of as one course actually has two underlying objects - the course, and the courselisting. The course has an ID field that links it to the courselisting id.
  • If two are more courses are cross-listed, they share the same courselisting object. 
    • Example: Suppose you have three courses that are cross listed - History 201, PoliSci 210, and German 203. 
      • There are three course objects - a separate one each for History 201, PoliSci 210, and German 203.
      • There is one courselisting object that is shared between the three courses. That means that if you looked at the course object for each of the three courses, they would all have the same courseListingId.
  • Links to instructor information are stored on the courselisting object - that means that if courses are crosslisted with each other, they will all show the same instructors. There is no way for crosslisted courses to have a different instructor for each crosslisting. 
  • The link to a term is stored on the courselisting object - that means that if courses are crosslisted with each other, they will all have the same term.
  • Items on reserve (stored in reserve.json) link to the courseListingId - this means that all crosslisted courses share the same list of reserve items. There is no way for crosslisted courses to have different items on reserve for different crosslistings.
  • If you are migrating course data, you'd create the courselisting, and then the course (since the course needs the courselisting ID to be properly linked.)

How reserve item records are stored in underlying data, and how those records interact with Inventory

To place an item on reserve, a FOLIO user goes to a course and adds the item using either a barcode, or the Fast Add functionality. Fast Add does not require a barcode to be used, so items can be added without a barcode. However, if the item has to be removed and then readded, the library must go into Inventory and add a barcode to the item so that you can use the workflow to add an item with a barcode.

When an item is added on reserve, the Courses app:

  • Creates a reserve record following the reserve.json schema: 
  • As part of the reserve record, makes a copy of specific parts of the inventory record (instance/holding/item) and keeps them as part of the reserve record for searching and reporting purposes;
  • If the Course has a location set on the associated courselisting object, Courses pushes the course location to the item temporary location field in Inventory. It does this even if the already existing effective location for the item matches the course location. 

When an item that is on reserve for one course is then put on reserve for another course, the Courses app:

  • Creates a reserve record following the reserve.json schema, with copies of specific parts of the inventory record as noted above. This means that you may have multiple reserve records for the same item.

When an item is removed from reserve from all courses (if it was added to multiple courses at the same time);

  • The temporary location is removed from the item record in inventory (if set on the reserve item);
  • The temporary loan type is removed from the item record in inventory (if set on the reserve item);
  • The reserve record is deleted

Important tips to know:

  • Once an item is put on reserve, changes to the item in Inventory do not populate to Courses automatically. (This is correct as of the Kiwi release.) That means that if you make a change to an item in Inventory and you want it to populate to Courses, you must take the item off reserve and put it back on reserve for the course to get the change to populate over. 
  • Courses follows its own algorithm to determine how to set the copied-over temporary location and permanent location attributes on the reserve record.
    • If the item has a permanent location field, it will set the reserve permanent location to the item permanent location.
    • If the item does not have a permanent location field set, it will set the reserve permanent location to the holding permanent location. 
      • Remember that only the holding permanent location is required in Inventory - and if no other location field is set, the item's effective location is inherited from the holding permanent location.
    • If the item has a temporary location field, it will set the reserve temporary location to the item temporary location.
    • If the item does NOT have a temporary location field, it will leave the reserve temporary location field blank ← need to verify this