3. Requests Import
eReserve Plus enables the scheduling of Readings via Request records, typically from Academics. A Request adds start and end dates to Readings so that they are processed through a workflow for approval to be added to the Reading List, for the correct duration. Readings Lists are served up to Students for a Course during the period (set on the List) via the Learning Management System.
The benefits of the Request Import is that it can combine the Readings and Requests in one process to create Reading Lists and related records. The Requests Import may also be more suitable for initial data migration because it allows for sub-prime Readings; that is data that does not meet the validation requirements of eReserve Plus.
This import is suitable for creating new Reading List records (find_or_create) or supplementing existing Reading Lists with new records (find_only).
3.1 Pre-requisites
-
Courses - Ensure the courses are setup in eReserve with unique Course codes. Ensure the Courses referenced in this Requests Import have the correct references to the Courses already created.
-
Teaching Sessions - The list of teaching periods called Teaching Sessions should have been pre-defined at Project setup. To check whether Teaching Sessions are implemented visit Configuration > Teaching Sessions.
-
Create a generic Academic account - all Requests imported in this way are identified as coming from this Academic account, typically a generic Library Staff email account. To create a new user visit Users > New and create a new user with the role of Academic. The email address for this user is used in the requester_email field.
-
Copyright email address for Requester email - The Copyright email address can be used in the requester email field for the Reading Requests to be automatically approved.
-
The Archive folder will need to be prepared as a .zip folder which should contain the following elements:
a. The Data File - This is a CSV file in UTF-8 file format - Filename = import_records.csv
b. The Mapping File - This is a YML file which references the data to map it to the correct fields - Filename = csv_to_document_mapping.yml
c. The Resource Folder - is a folder which should contain any physical files (e.g. PDFs, MPGs, JPGs etc) referenced in the Data File. All resources should be saved into the Resources folder with each file saved with its reference in the Data File. e.g. thedish.pdf
The templates and a sample dataset for each genre are available for use here
3.2 Data requirements
To ensure the import can process the data there are some mandatory fields required and an explanation of these follows depending on the duration of the Reading List. Before exploring duration it is important to consider the location – reading_list_locate_mode. If performing an import for the first time where the Reading List record does not yet exist the reading_list_locate_mode should be set to find_or_create.
If however, the import is being performed to add further requests and readings to an existing Reading List then the reading_list_locate_mode should be set to find_only. There are some matching rules to be aware of:
Custom Duration - attempts a match on the name of the reading list then if there is no match it will attempt to match on the duration (i.e. the start & end date)
Predefined Duration - attempts to match on the predefined duration (aka Teaching Session)
3.3 Mandatory Data - Duration
Requests apply a start and date to the use of a Reading and therefore additional metadata is required to create Requests, which in turn attach to a Reading List. There are two types of duration – Predefined (aka Teaching Sessions) or Custom dates. The mandatory data associated with the duration is explained below.
Reading Lists that are intended to have a Predefined duration utilise the associated Teaching Session and reference the correct code. Teaching Session codes are created by the system when they are entered. Examples include TS1, TS2 etc.
| Column | Description | Type | Suggested Value |
|---|---|---|---|
| reading_list_locate_mode | The method used to find the associated reading list | Text | find_only or find_or_create |
| reading_list_duration | Duration of the reading list | Text | predefined |
| teaching_session_code | Represents the code for the associated Teaching Session that defines the duration. | Text | e.g. TS1, TS2, TS3 |
There are some specific validation rules to be aware of in relation to Reading lists with predefined durations:
- Only one Reading List can be created, per course, per duration
- A Reading List for predefined duration cannot be created if a custom duration Reading list exists with the same duration.
Reading Lists that are intended to be created with a Custom duration typically fall out of the predefined durations (i.e. short courses such as summer schools).
| Column | Description | Type | Suggested Value |
|---|---|---|---|
| reading_list_locate_mode | The method used to find the associated reading list | Text | find_only or find_or_create |
| reading_list_duration | Duration of the reading list | Text | custom |
| reading_list_name | This is the name of the reading list | Text | e.g. 2019 Summer Intensive |
| reading_list_start_date | This is the date that the readings on the reading list become accessible to students. | Text | Your local date format e.g. DD/MM/YYYY or MM/DD/YYYY |
| reading_list_end_date | This is the date that the readings on the reading list are no longer accessible to students. | Text | Your local date format e.g. DD/MM/YYYY or MM/DD/YYYY |
Reading Lists with Custom durations also have validation rules to observe:
- Reading list names must be unique
- Reading list durations must be unique (i.e. no two lists can have the same start & end date).
3.4 Mandatory Data - Requests
The mandatory data to import Requests is minimal as the intention is for Library Staff to collect or finalise any missing data once the Request is initiated in the system. The Request will be processed via a Workflow so there is opportunity to correct missing data. The minimum data requirements are outlined below:
| Column | Description | Type | Suggested Value |
|---|---|---|---|
| source_document_title | The title of the document | Text | Data Dictionary |
| source_document_kind | The kind of source document associated with the reading (e.g. book, journal, etc.) | Text | Data Dictionary |
| source_document_licence | The licence for the source document | Text | Data Dictionary |
| reading_title | The title of the reading | Text | Data Dictionary |
| reading_genre | The genre of the reading itself (e.g. chapter, journal article, legal article, etc.) | Text | Data Dictionary |
| reading_kind | Denotes whether the reading is a FILE or a LINK or needs to be located | Text | Data Dictionary |
| reading_reference | The file or link associated with the Reading | Text | Data Dictionary |
| course | The code for the associated course of learning (e.g. Course, Subject, Paper, etc) that the reading is to be made | Text | e.g. CS101 (with course code filter) OR CS101_s2_2018 (without course code filter) |
| start_date | The date from which the reading is to be made available to students | Date | Your local date format e.g. DD/MM/YYYY or MM/DD/YYYY |
| end_date | The date when the reading is no longer available to students | Date | Your local date format e.g. DD/MM/YYYY or MM/DD/YYYY |
| reading_importance | Denotes if the reading is required to be read by Students | Text | Data Dictionary |
| requester_email | The email address for the academic account created as part of the prerequisites for import (see chapter 5.1) | Text | The email address for the academic account created as part of the prerequisites for import. See 3.1 |
3.5 Additional data requirements
There are a number of secondary data requirements which are optional and are not required for the import of Requests to be successful. This optional metadata can be explored required_fields_for_flat_file_import.