Ares to Leganto Migration Guide
- A step-by-step guide to filling out the Ares to Leganto Migration Form
- A description of data elements expected, and how they are mapped using the Ares to Leganto Migration Form.
- An explanation of general migration rules which do not require any customer input
Recommendations for Using this Guide
This document is divided into two areas:
- Courses
- Reading Lists
Each area has the following sections:
- File Information: Information on files that are expected from Ares and where incoming fields are mapped in Leganto, including functional implications.
- Migration Form: Questionnaire Tab – Instructions for individual questions asked on the Questionnaire tab of the Migration Form.
- Migration Form: Individual Tabs – Instructions for how to fill out individual tabs on the Migration Form.
We recommend that you look at the Questionnaire tab section and the individual tabs in each area to assist in filling in the migration form.
For more information about any of the data input or about the migration in general, see the more detailed explanations in the Further Explanations sections.
Related Documentation
- This document is intended to complement the Ares to Leganto Migration form - an Excel spreadsheet that is read by the migration programs. It provides further information regarding the migration process and the steps required for migration to Alma.
- Prerequisites: Basic knowledge of Alma and Leganto key concepts and architecture. You may also wish to consult the Leganto documentation.
Migration Overview
- Export Course and Reading Lists from Ares (customer responsibility)
- Indicate which local fields correspond to the Leganto expected fields using the Course and Reading List tabs of the Ares to Leganto Migration Form (customer responsibility).
- Complete the Ares to Leganto Migration Form.
- Upload the files to Ex Libris’ secure file server (MFT) along with the completed Ares to Leganto (customer responsibility).
- Transform the data elements, based on the Field Mapping form, into an intermediate tab-delimited format (Ex Libris migration team responsibility).
- Load the transformed data into Leganto (Ex Libris Professional Services responsibility).
General Format of incoming files
The incoming files should be in CSV (quotes/commas) format, as they are exported from Ares. Please ensure that there are no linebreaks within the data, for example sometimes there are notes with carriage returns, which make the entire line unreadable.
Courses
Course files should be delivered in csv format (quotes and commas).
Let Ex Libris know how to map your incoming fields using the 'COURSE field mapping' tab on the ARES to Leganto Migration Form. The following fields are expected from ARES:
| Expected Field Name | Notes |
|---|---|
| Course ID | This is ONLY needed to link to Reading List/items. This is an internal ARES key which is only used for linking, and will not be loaded into Alma/Leganto. |
| Name | Course Title; this is mandatory. This is also placed in the Reading List Name field. |
| Course Code |
This is mandatory; either use Course Code field or something else like External Course Id. This is the primary unique key for courses in Alma/Leganto. This field will be placed in the 'to be loaded' Reading list file, so that this code can be used as the link between course and reading list. |
| Semester | Use the Term Mapping tab to transform this to the Terms code table |
| Year | If you wish to use the first four digits of the 'Semester' tab to go into 'Year', put 'Semester' here. |
| Section | There is no incoming field called 'Section'. You may choose to put another field here |
| Start Date | In date format specified |
| Stop Date | In date format specified |
| Department | Use the Academic Dept tab to transform this to the Academic Department code table |
| Instructor | Must be an Alma Primary ID; provide external file if necessary. See External Files section below. |
| Default Pickup Site | Use the Processing Dept tab to transform this to the Processing Department code table |
| Course Enrollment | Integer |
| External Course Id (search ID 1) | If this is not supplied in the file, you can provide an external file which maps from Course Code. This is placed in Search ID1. See External Files section below. |
| Search ID 2 | You may choose any field to put in search ID2. |
Items (Reading List )
The incoming item file should be provided in CSV format (quotes/commas). This is transformed to the ALma reading list.
Let us know how to map the incoming fields to the Leganto format using the 'ITEM field mapping' tab of the ARES to Leganto Migration Form. The following fields are expected from ARES:
| Expected Field Name | Notes |
|---|---|
| Course ID |
needed to link to course file. This is an internal ARES key and the only thing it is used for is linking to the course file. It is not loaded into in Alma. For the 'to be loaded' Reading List file, this is not sued. The actual 'Course Code' is going to be used to link between the course and reading list files for load. |
| Item ID | Original system ID from ARES (not an Alma ID) |
| Processing Location | use in RL Assigned To tab, to map to an Alma patron ID |
| Location | If this contains http, then this is put in creation source. If a file, then there should be an external file for loading |
| Copyright Required | use in Creative Commons mapping tab |
| Copyright Obtained | use in Creative Commons mapping tab |
| Title | |
| Author | |
| Publisher | |
| Pub Place | |
| Pub Date | |
| Edition | |
| ISXN | |
| Cited In | |
| DOI | |
| Article Title | |
| Volume | |
| Issue | |
| Pages | |
| Item Format | use in Citation Material Type map |
| CCC Number | |
| Editor | |
| Item Barcode | If desired, provide an "Item Barcode to MMSid" map. If an external map is not provided, no attempt is made to link to an Alma MMS record. See External Files section below. |
| Item Info1 | |
| Section | this is not an ARES field but you can place something here if desired, if you want the 'Section' field in Leganto to be filled. |
| URL | |
| Semester | used as part of the reading list code |
| Start Date | |
| Stop Date | |
| Instructor Tags | will be placed in citation instructor note |
Optional Note fields
The following fields are notes or note-like. You can place any incoming field in the following expected fields.
| Expected Field Name | Notes |
|---|---|
| reading_list_library_note | |
| reading_list_instructor_note | |
| citation_tags | Tags must already be defined in Alma |
| citation_source1 | |
| citation_source2 | |
| citation_source3 | |
| citation_source4 | |
| citation_source5 | |
| citation_source6 | |
| citation_source7 | |
| citation_source8 | |
| citation_source9 | |
| citation_source10 | |
| citation_note | Migration already puts two things here: Item Info, and Article Title if this is a Book. |
| citation_library_note |
External Files
In order to successfully match Ares data with Alma data or other systems, you may provide external maps, for both course and reading list.
External Course ID (for course file)
If you have an external course ID, you can provide a map of Ares Course Code -> External Course ID. For example, you might have an identifier for the course in an external campus system, and you may want to use that code to link to this external system.
The mapping file should be simple, like:
BIO101,BIO5674-LIB223
Instructor (for course file)
In order to link courses to instructors, the file to be loaded must have an identifier associated with an Alma user. The string of the instructor's name is not enough for a match. The map for the instructor to Alma user identifier should be placed in the Migration form, 'Instructor' tab.
For help on retrieving a list of identifiers, see Appendix B - Instructor to Primary ID.
Item Barcode -> Alma MMSID (for Reading List file)
If you have an item barcode in the reading list file, you can use Alma Analytics to retrieve the Alma MMSID. The link between reading list and Alma inventory is via the MMSID, not through the item. Provide this file as a simple external CSV file, with two columns:
Item Barcode,MMSID
For help on retrieving a list of MMSIDs based on a list of barcodes, see Appendix C - Barcode to MMSID.
Migration Form
Questionnaire tab
Institution Code, Customer Code, Institution Name, Customer Name
Codes: INST_CODE, CUST_CODE – these are filled in by Ex Libris
INST_NAME and CUST_NAME: These are informational.
Incoming Date Format for ARES
Code: DATE_FORMAT_ARES
Default: yyyyMMdd
Options: List the date format for the incoming date from ARES. MM = two digit month, dd = two digit day, yy or yyyy = year. Examples: yyyyMMdd, MM/dd/yyyy
Date Format as Listed on Integration Profile in Alma
Code: DATE_FORMAT_ALMA
Default: yyyyMMdd
Further Information: On the Alma/Leganto Integration Profiles used to load courses and reading lists, there is a line for 'Date Format'. List that date format here. MM = two digit month, dd = two digit day, yy or yyyy = year. Examples: yyyyMMdd, MM/dd/yyyy
FYI, your Ex Libris representative will help you set up this integration profile.
To see the integration profiles, go here: Alma Configuration Menu –> General –> External Systems –> Integration Profile. Integration Type = 'Course Loader'
Reading List Visibility
Code: RL_VISIBILITY
Default: PUBLIC
Options: DRAFT, PUBLIC, RESTRICTED, REGISTERED, OPEN_TO_WORLD ,PARTIAL, FULL
Further information: Select the default visibility for all of the reading lists. This is also known as the Publication Status, and more information can be found on the Managing Reading Lists page.
Limit the Migration to only recent courses
Code: LIMIT_COURSE
Default: N/A, this is not mandatory
Options: Type a four-digit year (e.g. 2021), and the migration will migrate courses for 2021, 2022, 2023, 2024 etc. The migration checks the first four digits of the 'Semester' field.
Term
Use this tab to map incoming 'Semester' column to an Alma Term. This field is mandatory, so an ALMAME_VAL_NOT_FOUND line is required.
Incoming Semester: Semester field from the Course extract. Usually in the format yyyyMM, like '202301'
Description: a description of the incoming field, for note purposes and not used in the map/migration
Alma Term code: A dropdown list of available term codes in Alma.
Alma Term Description: You must use the existing list of Leganto term codes, but you can use whatever name you wish. The Description associated with the first instance of the code will be loaded to Alma.
Academic Department
Use this tab to map the incoming 'Department' field to the Alma 'Academic Department'. Columns C and D from this tab are used to generate the Alma code table for Academic Departments. This field is mandatory, so an ALMAME_VAL_NOT_FOUND line is required.
Incoming Department: 'Department' field from the Course extract.
Description: a description of the incoming field, for note purposes and not used in the map/migration
Alma Academic Department code: A code for the academic department.
Alma Academic Department Description: The description for the academic department.
Further information: For more information see the help guide for Academic Departments.
Processing Department
Use this tab to map the incoming 'Default Pickup Site' to the Alma 'Processing Department'. This tab is NOT used to load anything into Alma, this is a map only. This is mandatory so an ALMAME_VAL_NOT_FOUND line is required.
Incoming Default Pickup Site: 'Default Pickup Site' field from the Course extract.
Description: a description of the incoming field, for note purposes and not used in the map/migration
Alma Processing Department: A code for the processing department.
Further information: For more information see the help guide for Processing Departments.
RL Assigned To
Use this tab to map the incoming 'Processing Location' to an Alma staff user account, by providing the user's Primary ID. This is not mandatory, if nothing is assigned, then it shows up on the 'Unassigned' tab.
Incoming Processing Location: The 'Processing Location' field from the Reading List input file.
Description: a description of the incoming field, for note purposes and not used in the map/migration
Alma Primary ID for Reading List assignment: The primary ID of an Alma staff user, for reading list assignment.
Creative Commons
Use this tab to map the incoming copyright fields to an Alma Creative Commons value. This field is not mandatory, so ALMAME_VAL_NOT_FOUND is not required here.
Incoming fields: The two incoming fields for this map are: 'Copyright required' and 'Copyright obtained'. They are both TRUE/FALSE.
Alma Creative Commons value: The list of possible creative commons values are listed in the dropdown for this column.
Further information: for more information on copyright in Leganto, see Configuring Leganto Copyright-related Procedures.
Citation Material Type
Use this tab to map the incoming Ares reading list item format to a citation type in Alma/Leganto. This field is mandatory, so the ALMAME_VAL_NOT_FOUND is required.
Incoming Item Format: The value from the 'Item Format' field in Ares.
Description: a description of the incoming field, for note purposes and not used in the map/migration
Alma Citation Material Type: The column in the spreadsheet contains a dropdown of possible values for this field.
Be aware that the mapped value here is used to determine if the Alma/Leganto field 'Citation Chapter Title' contains the Ares field 'Title' or 'Article Title':
If Item Format (mapped) = BK or CR then try to fill in Citation Chapter TItle. First, use Article Title. If Article Title is blank then use Title anyway. If both 'Title' and 'Article Title' are blank (and it's BK or CR) then say ‘Unknown Title’.
Instructor Map
The instructor map should contain two text columns.
Column A: the text in the 'Instructor' field in the incoming course file
Column B: an identifier from Alma which represents this instructor
For instructions on how to retrieve an identifier given a string, see the Instructor section in "External Files" above.
Appendix A – Delivering Files
Appendix B - Instructor to Primary ID
Alma requires an Instructor's Alma Primary ID to link an instructor to a Course.
Ares default course information includes Instructor name(s) and Instructor Display Name. An optional (recommended) field to include is a "Created by" identifier in the course extract.
Usually none of the values is the Alma Primary ID, so a mapping from the Ares value to Alma Primary id is needed for the Instructor tab on the migration form. The following are the suggested steps for creating such a map.
First, Create a Unique List of Instructors.
1. Work from a copy of your exported Courses file from Ares.
2. Select the Migration Form field for 'Instructor' in the Courses file. Determine which field of those included in the Courses extract (Instructor Name, Instructor Display Name, or Created by) is most accurate. This is the field you should include in the Migration form as your "Instructor".
3. Create a unique list (deduplicated) of chosen 'Instructor' values and their ARES unique identifier (possibly Created By ID). Identifier could be Alma Primary Id, any Identifier or email address. This may require programming/reports from ARES or another system to link Instructor names to an identifier which is in Alma. If this unique list's identifier is also their Alma Primary ID, skip to the last step of adding this information to the Migration form, instructor tab.
4. In Alma, use the Ares unique ID provided and Analytics to 'lookup' the Primary ID. Below is one possible method:
Alma Analytics Suggested steps
If you already have the Alma Primary ID, these steps are not needed.
a. In the saved unique list of Instructors and IDs, sort by the IDs
b. Dedup the IDs - You may wish to group the IDs into sections of a few hundred for extract from Analytics. You will be copying/pasting into Analytics.
c. Go to Alma > Analytics > Access Analytics
d. Create > Analysis > Subject Area > Users
e. Add User Details > First and Last Name; Full Name; Identifiers > Identifier Type and Value; Email > email (Only add necessary
f. Add Identifier: Identifier type and Identifier value > filter this type to match the type of identifier provided in the Unique List
g. Add Email: email field - only if email was the ID provided in the Unique List
h. Filter the Idenfier or Email value field "is in"
i. Per https://knowledge.exlibrisgroup.com/Alma/Knowledge_Articles/How_to_Use_a_List_of_Values_from_a_CSV_File_as_a_Filter_in_Alma_Analytics,
edit the "selected" column to paste in the instructor dedup'd ids saved in Step b. Save the filter
j. Save the criteria
k. Run the results
l. Export the results.
m. Make sure the results match the number of expected ids. You may run the entire list of IDs at one time or break the list into smaller groups and repeat steps h-m.
n. Once all results are extracted and available, update the instructor tab of the migration form with the value for "Instructor" and the correct Alma Primary ID.
Appendix C - Barcode to MMSID
Alma can link courses to inventory, but the required link is the MMS id (bib key). Typically in Ares, the link to inventory is the item barcode. This section describes how to retrieve a list of MMSids given a list of barcodes.
From Item details file
1. Find barcode columns
2. Filter to barcodes valid barcodes (remove blanks, any inaccurate fields like call numbers, item formats, etc.)
3. Select all remaining values
4. Copy to Notepad++
5. Add a column header "Barcodes"
6. Save as text file (barcodes.txt)
In Alma
1. In Alma, create itemized set from the file > Admin > Manage Sets > Create Itemized Set
2. Any set name
3. Change set content type to 'Physical Items'
4. Change 'Add items to set' to "from file"
5. Drop a file or Upload the Barcodes.txt file
6. When set created, go to 'Content' > Use the 'Export List' feature for Excel (All fields) to download the excel results
Excel resulting item file
1. Create a copy of the extract "result" excel before opening
2. Delete all columns except Item barcode and MMS id - be sure column type for both are changed to TEXT so numbers are not corrupted.
If there is a problem with corruption, you may need to open the copy with a tool such as "CSVed" which is a free editing tool which
would allow the deletion of the columns without altering the longer numerical data.
3. Save as a csv file
4. Send to ExLibris to SFTP server being used for migration