Licenses Data Mapping Guide: FOLIO to Alma

Purpose: This page describes data mapping from the FOLIO Licenses app to Alma.  During the Alma implementation phase beginning in the fall of 2023, these pages serve as working documents for decision-making about data migration.  Once the migration to Alma is complete, these guides will be retained for reference.

Overview

This page defines the requirements to create a file of FOLIO licenses in the format defined by Ex Libris for loading to Alma. This process will happen twice: once during the Test Load in December 2023 and once during the cutover period in June/July 2024.

FOLIO

There are 716 license records in FOLIO as of 11/28/23. Each license contains a URL link to the core license document on Box, can optionally link to one or more organization records, contain multiple amendment records, multiple notes, multiple terms of use, and multiple URL links to Box for supplementary documents. There are no links to orders or inventory in FOLIO license records. This is a screenshot from FOLIO of an example license record:

Assumptions

1. Loading the license data to Alma will be completed by Ex Libris. They will load the license file that we provide (we won’t be using Alma APIs to do this migration).

Completion Criteria

• Jan 2024: All FOLIO License records exist in the Alma Test environment.

• July 2024: A fresh extract of FOLIO License records is run and are loaded to the Alma Production environment

Data Sources

The data needed for this FOLIO License extract is available from the following APIs:

1. FOLIO Licenses API Most of the data for the license file is stored here.

2. FOLIO Organizations API We need data from the organization record to populate the Alma license_details/licensor_code.

3. FOLIO Notes API We need to query the Notes API to pull any notes associated with the licenses. It looks like there are 51 note records associated with the license domain.

Extract and Transformation Requirements

Mapping for each data element that we need to send to Alma is documented in this spreadsheet on Box: FOLIO to Alma Data Mapping Excel Sheet. The following section gives a fuller explanation of some of the requirements for this extract.

Ownered Entity

License Code

License Status and License Review Status

Amendments

View of License list in Alma highlighting how the Amendment License Code looks to users:

Licensor Code

We need data from the FOLIO organization record to populate the Alma license_details/licensor_code.

If the FOLIO orgs/0/primaryOrg = TRUE, use the UUID value in orgs/0/org/orgsUuid to query the FOLIO organizations API to determine the appropriate vendor code to populate the Alma license_details/licensor_code using the following logic:

Another example: 0b66713f-a65b-41bd-b186-a5cbb7b6bca8

• If any of the alias 1 -7 value fields contain the string “No aleph vendor code”, use the code value from the organization record to populate the Alma license_details/licensor_code. 

aliases/0/value….aliases/7/value

Location Code

The Alma UI includes a “license location” value (see screenshot below). Our FOLIO licenses are all stored digitally in Box, so we will add a new license location with a code value = ‘BOX.’ Send ‘BOX’ as the location code value on all records.

Terms of Use

See the mapping spreadsheet for the set of terms of use mapping. Some FOLIO values map directly to Alma, but others that don’t already exist in Alma will be added manually as new custom terms by ExLibris staff.

Most terms of use entries in FOLIO contain an internal note; however, some customProperties/{term}/0/value/label are set to "Yes", but have a null customProperties/{term}/0/note value. In that case, send the text, "Yes" as the note value.

Reference documentation

• FOLIO to Alma License Migration Guide
• Managing License Terms

• FOLIO Licenses Data Migration Folder on Box

  • Full extract of licenses pulled via the FOLIO licenses API from production on 11/9/23

  • FOLIO to Alma Data Mapping Excel Sheet

• Link to Basecamp notes from 11/21 focused meeting with ExLibris about this migration

Resolved Questions

1. We need to create some new custom license terms in Alma. How do we set those up in the Test environment prior to the load of licenses? Answer: ExLibris staff will manually create those for us to enable the load to run without errors

2. The 11/21 meeting with ExLibris experts raised questions about how to migrate our URLs for the supplementary documents. Answer: After review and testing, they reported that we can’t send in those URLs in the attachment section and recommended that we map them as a note.

3. Alma has fields in the UI for a Licensor organization and a Licensing agent organization.

   1. There isn’t a licensing agent element in the XSD definition - should there be? Answer: ExLibris and they suggested we could request this and they’d need to check on how long that would take.

   2. We decided to map organizations as a note since there wasn’t time to make changes to the ExLibris generic vendor load XSD.

Action Items

1. Resolve Attachments question - how to map FOLIO supplementary document URLs to Alma? Julie posted a question on the ExL Basecamp message board on 12/5. Still waiting for guidance as of 12/7. Update 12/11: Marie tested and couldn’t successfully send in a URL as an attachment, so the team recommends we send them in as a note value. Julie added that note string definition above. - Complete

2. Add field-level amendments mapping to the spreadsheet in a new column (green) (Julie) - Complete

3. Ask end users which order the amendments naming convention should follow (Julie) - use start date - Complete

4. Get info from Virginia about how to handle null start dates in FOLIO - is there a date we can use for all of them such as 1/1/1950. Reply received 12/11/23 - use date ‘1/1/1900’. Complete.

5. Confusion about how to format ampersands - open conversation on basecamp 12/18. Chana confirmed that we need to send &. Complete.