Historical Entitlements Import

Overview

The historical entitlements import is available to all Order Tool institutions. This import might be used to support the addition of a learning tool (e.g. TopHat Classroom) to an institution’s catalog. For example, an institution might seek to add TopHat Classroom to its catalog and require a backfill of historical entitlements to ensure that students are not overcharged. These historical entitlements represent purchases that students made outside of Order Tool but allow them to access TopHat Classroom for the lifetime of their enrollment. By importing an institution's historical entitlements, students will not be charged again for use of the learning tool in future courses where it is adopted (where the entitlement is valid). Order Tool will have a record that the student has an entitlement and report it accordingly in the Final Declined Offers Feed based on the import of historical entitlements.

To run the historical entitlements import, please reach out to the Unizin Services team via email at [e-mail] to discuss your use case. When proposing your use case, please provide details of the digital course material you’re seeking to add to your catalog in Order Tool and the reason that a backfill of historical entitlements is required for this.

Implementation

Unizin will work with the institution to add catalog items and offers for a specific learning tool. Collaboration is also needed to determine the type of backfill offers that must be created for the digital course material.

Since there must be, at most, one offer per academic term, a backfill academic term must be created by the institution for every backfill offer needed. For example, an institution might want to backfill entitlements where students are entitled to the catalog item for the lifetime of their enrollment and for 1-year access. Given this example, the institution would create two backfill academic terms which will be added to the SIS Feed for one import. The terms in this example would be:

• 1-Year Backfill

• Lifetime Backfill

The Unizin team will archive these two terms after a successful import. The institution would only need to provide these backfill terms once. Once the academic term is archived, the term start and end dates will be set by Unizin to 01/01/2000 to 12/31/2000, respectively.

Next, the Unizin team will create a backfill offer for each backfill term. These offers must be associated with the same content record, and that content record will be the same record used for future offers. The list price, offer price, and student price for each backfill offer will be $0 since it was paid for outside of Order Tool.

Once the backfill offer records are created in an institution’s production tenant, the offer ids will be provided to the institution. From here, the institution (often in partnership with the publisher or learning tools vendor) will create an “entitlement.csv” file.

Next, an institution will upload the “entitlement.csv” file to their “sis-data” bucket, for the appropriate environment (UAT or PROD) to BrickFTP. The Unizin team recommends testing this import in UAT prior to performing it in an institution’s PROD tenant. To run the import, the Unizin Services team will run the import on an agreed-upon date. Once the import is complete, the Unizin team will provide a report describing the outcome of the import. In the case that some entitlements could not be created, those records will be communicated to the institution for review.

Unizin will also discuss with the institution how they intend to facilitate ordering for this digital course material in the future. For some institutions, it might make sense for the Unizin team to add these offers manually. For other institutions, it might make sense to provide content and offers through the Institutional Catalog Import. The Unizin team will work with you to determine the best approach for your use case.

Entitlement.csv

The entitlement.csv file must contain all data outlined below.

Field name	Data type	Description
email	Text	This field is required. In order to capture an entitlement, it must map to an email address for a user in your Order Tool tenant. Users are provided in your SIS Feed.
start_date	Date	This field is required. It must be formatted as YYYY-MM-DD. The start date will be used to calculate the end date for the entitlement based on the length of access defined for the offer. For example, if a student has an entitlement starting on 2020-01-01 for one year (based on the length of access defined in the offer), then their entitlement end date will be calculated as 2021-01-01.
offer_id	Integer	This field is required. These values will be provided by the Unizin team. There will be one offer_id for each type of entitlement. For example, if entitlements will be captured for 1-year and 6-month access, then two offer_ids will be provided. It is the responsibility of the institution to map these to student emails accordingly.

For additional information, please see our File requirements documentation here.