Reading List Loader
File Specifications
- Each citation must be on one row of the file.
- A header row is mandatory and skipped.
- Similarly, all sections within a reading list must be grouped together, and all reading lists within a course must be grouped together.
As each line from the same reading list is read, it is stored in memory. When a new reading list is detected, the reading list is created and all lines in memory are added to the list.
- The input file must be tab-delimited. Comma-delimited files will not work, as commas are legal characters in the input file, used to separate values within a tab-delimited field.
- All fields must exist in the file, even if they are empty. Fields that are labeled "mandatory" below are fields that must have values and cannot be left empty.
- Fields (all fields are strings, unless noted; permitted values are case sensitive):
The fields course_code, section_id, reading_list_code, reading_list_name, reading_list_description, reading_list_status, and owner_user_name uniquely define a reading list. As lines are processed, if any of these are different from the previous line, a new reading list is assumed. If a line would create a new reading list that contains the same reading_list_code as an already existing reading list, the line is ignored.For example, if you have two lines where the reading_list_codes are the same but the reading_list_names are different, the second line represents a new reading list, but it contains the same code as an existing reading list, so the line is skipped. If you have two lines where the reading_list_codes are different but the reading_list_names are the same, the second line represents a new reading list with a different code (both reading lists have the same name).The fields section_name, section_description, section_start_date, and section_end_date uniquely define a section. As lines are processed, if any of these are different from the previous line, a new section is assumed. There can be multiple sections with the same name.
- course_code – An existing course code within Alma. If not supplied or the code cannot be found, the reading list is not associated with a course. Courses cannot be created using this tool.
- section_id – Section ID of the course. Relevant only for a course defined in Alma.
- searchable_id_1 – Alternate ID that may be associated to a course.
- searchable_id_2
- searchable_id_3
- reading_list_code (mandatory) – The reading list code. Max 50 characters.
- reading_list_name (mandatory)
- reading_list_description
- reading_list_subject – Reading list subject codes, separated by commas. Invalid subject codes are ignored. Subjects are listed in Editing a Reading List in the Alma documentation. Subject codes are the subject names in capital letters, with spaces replace with underscores (for example, ECONOMIC_THEORY).
- reading_list_status (mandatory) – The reading list status: BeingPrepared, ReadyForProcessing, BeingProcessed, Complete, Inactive, or Declined. A valid status is required. Note that custom statuses defined by the institution are supported for this field.
- RLStatus – The reading list publication status: DRAFT (default), ARCHIVED, PUBLISHED.
- visibility – The reading list’s visibility status:
- DRAFT – If RLStatus is DRAFT, set this to DRAFT as well.
- RESTRICTED – Only course students can view the list and access the course materials.
- PUBLIC – All authenticated Leganto users can view the list but only course students can access restricted course materials.
- REGISTERED – All authenticated Leganto users can view the list and access any restricted course materials.
- OPEN_TO_WORLD – Anyone, including guest users, can view the list, but only course students can access any restricted course materials.
- PARTIAL – Anyone, including guest users, can view the list, but only authenticated Leganto users can access any restricted course materials.
- FULL – Anyone, including guest users, can view the list and access all course materials.
- reading_list_assigned_to – The user ID of the librarian to which the list is assigned.
- reading_list_library_note – You can add one note of type Library for the reading list. You can not add multiple notes at this time.
- reading_list_instructor_note – You can add one note of type Instructor for the reading list. You can not add multiple notes at this time.
- owner_user_name – The reading list owners, separated by commas; any valid Alma user identifiers defined for your institution are permitted. All IDs must exist in Alma; if they do not exist, they are ignored.
- creative_commons – The creative commons code for the entire reading list, if any. See Configuring the Default Creative Commons Value for a Reading List for possible statuses.
- section_name (mandatory)
- section_description
- section_start_date (dd-mm-yyyy) – If the format is not correct, null is assumed.
- section_end_date (dd-mm-yyyy) – If the format is not correct, null is assumed.
- section_tags – A comma-separated list of tags for the section. A tag that does not exist is ignored.
You must ensure that the end date is after the start date. The tool does not validate this. If the end date is before the start date, this may cause some display issues in Leganto.
- citation_secondary_type (mandatory) – The citation’s material type. One of:
- ABSTRACT
- ANTHOLOGY
- AR – audio recording
- ARCHIVE
- AW – artwork
- BK – book. BK is the default, and is used for an empty or invalid value.
- BK_C – book chapter
- BL – blog
- CASE
- CASE_STUDY
- CD
- CONFERENCE – conference series, proceedings, or paper
- CP – computer program
- CR – journal or article
- DATABASE
- DISSERTATION
- DO – document
- DVD
- E_BK – e-book
- E_CR – e-article
- EOFFPRINT
- GOVERNMENT_DOCUMENT
- GRANT
- IM – image
- INTERVIEW
- JR – journal
- LEGAL_DOCUMENT
- LEGISLATION
- LETTER
- LIB_GUIDES
- MANUSCRIPTS
- MP – map
- MU – music
- NEWSPAPER_ARTICLE
- NOTE – Citations of this type are added by instructors in Leganto. They are used to provide information to the students who are viewing the reading list, and do not need to be fulfilled by the library staff.
- NP – newspaper
- OTHER
- PAMPHLET
- PATENT
- POEM
- PRESENTATION
- REFERENCE_ENTRY
- RESEARCH_DATASET
- REVIEW
- SCORE
- SERIES
- STANDARDS
- STATISTICAL_DATA_SET
- TEC_REP – technical report
- TEXT_RESOURCE
- TH – thesis
- TR – transcript
- VD – video
- WORK_PAPER – working paper
- WS – website
- citation_status (mandatory) – The citation status: BeingPrepared, ReadyForProcessing, BeingProcessed, Complete, Inactive, or Declined. A valid status is required. Note that custom statuses defined by the institution are supported for this field.
- citation_tags – A comma-separated list of tags (public or fulfillment) as defined in the configuration area. Invalid tags are ignored.
- citation_mms_id – The MMS ID.
- citation_originating_system_id – Used for tracking and to enable resource locate matching with the relevant bibliographic record's originating system id.
- citation_title (mandatory) – There can be multiple citations with the same name. For an article, use this for the article name and citation_journal_title for the journal name. For a journal, use this for the journal name and leave citation_journal_title empty. For a book chapter, use this for the book name and citation_chapter_title for the book chapter name.
- citation_journal_title – The journal name for an article citation.
- citation_author – Citation author. The field is read as a single string, including any commas (multiple authors are not parsed).
- citation_publication_date
- citation_edition
- citation_isbn – If an ISBN/ISSN is not provided, a thumbnail does not appear in Leganto.
- citation_issn – For a journal. If an ISBN/ISSN is not provided, a thumbnail does not appear in Leganto.
- citation_place_of_publication
- citation_publisher
- citation_volume
- citation_issue – The citation issue number or code.
- citation_pages – The page range of the citation.
- citation_start_page
- citation_end_page
- citation_doi – The citation digital object identifier: just the ID and not the URL.
- citation_oclc – The citation OCLC number (or any system control number).
- citation_lccn – The citation LCCN number.
- citation_chapter – The citation chapter number. Relevant for book chapters.
- citation_chapter_title – The citation chapter title. Relevant for book chapters.
- citation_chapter_author – The citation chapter author. Relevant for book chapters.
- citation_editor
- citation_source – The citation data source: MARC21 field 786 or 590, or any URL link to the source or full text of the citation.
- citation_source1 – Any additional source.
- citation_source2
- citation_source3
- citation_source4
- citation_source5
- citation_source6
- citation_source7
- citation_source8
- citation_source9
- citation_source10
- citation_note – A note about the citation. This note appears to the instructor in Leganto and to the student on the citation page.
- additional_person_name – Additional authors and/or contributors.
- file_name – Optionally upload a file for the citation. Files to upload must reside in a folder called files placed in the same directory as this file. If there is a problem reading/uploading the file, the process will continue and only the file for this citation will fail to attach.
- citation_public_note – A note displayed to students in Leganto on the reading list page.
- license_type – A license type for the citation, if any: SELFDECLARED for a self-declared copyright, or a creative commons code if any. See Configuring the Default Creative Commons Value for a Reading List for possible statuses.
- citation_instructor_note – You can add one note of type Instructor for citation. You cannot add multiple notes at this time.
- citation_library_note – You can add one note of type Library for the citation. You cannot add multiple notes at this time.
- external_system_id – Optionally used for transferring a CCC license. Value must be CCC_<license number>_<funded|nonfunded>, where <license number> is the CCC license key. Example: CCC_70193668_funded. If the rest of the citation metadata is present (including start and end page), Alma maps a valid CCC license to the citation. The copyright license status is Requires Renewal. Renew the license manually in the UI or by running the license renewal job.
Add a blank space to this field, rather than leaving it empty, to ensure that you do not get an invalid line size for the row.
Import Reading Lists Using the Reading List Loader
-
Add a new integration profile on the Integration Profile List page (Configuration Menu > General > External Systems > Integration Profiles > Select Add Integration Profile).
- In the Integration Profile screen, select "Reading List Loader" from the Integration Type dropdown.
- In the S/FTP Connection Type dropdown, select a connection type.
- Fill in the remaining required fields and select Next.
- In the Reading List Import screen, enter the Input File Path. This is the path to the .txt input file on the ftp server.
- Select to run the job in Report Mode if you wish. If selected, the job will not create reading lists, but rather simulates the creation and produce a job report as if reading lists were created.
Reading List Import - Select Input File Path
- If there are data files you wish to associate to the citations in the upload, you must put them into a folder named files, and put the folder into the same location as the input file.
files folder and input fileFor each citation in the .txt input file to which you wish to associate a data file from the files folder, the value of the file_name field in the .txt file must be identical to the name of the data file that you wish to associate to the citation.File_name fieldIf there is a problem reading/uploading a file, the upload process will continue and only that file will fail to attach.
- Select Save to save the integration profile.
- In the Integration Profile List screen, select the integration profile you have created and select the Actions tab. Select Run to run the job.
When the job runs, a reading list set is created with all list IDs created during the job. The set will be visible (type "Public"). The set name will be ReadingListLoader_<JOB_ID>.
A Reading List Loader job can be aborted at any time via the Monitor Jobs screen in Alma. When a job has been aborted, any reading list that has already been loaded will remain in the system.
Once the job has run, you can also perform updates on the created set using the Reading List Bulk Update job (see Reading List Bulk Update).
Validations
Prior to running the job, the system validates the data in the input file, to check for the following errors:
- Missing columns
- Rows with a corrupted row length (tab count is less than the required amount)
- Reading list code already exists
- The list is not in one block.
- The section is not in one block.
- Any of the following mandatory fields are missing for any rows:
- Reading list code
- Reading list name
- Section name
- Citation secondary type
- Citation status
- Citation title. If type is a book chapter, then the chapter title is mandatory.
- The same list code appears more than once in the file across random rows.
Empty lists are considered valid. Therefore if there are reading list names and codes but no section or citations, this is considered valid. In addition, if there are reading list names and codes and section names, with no citations, this is considered valid.
The following is an example of the events report for the lists created with warnings.
For each warning/error that the job produces, there will be a reference to the list and row number in the input file.