# Staff guide

## Roles

**Administrator:** manages semesters, staff accounts, imports, requests, allocation, cases and notifications. Can inspect a protected notification containing an access code; that preview is audited.

**Read-only viewer:** searches by university ID, name or email; inspects scholarship status, registration, book demand, code transaction status, Kortext delivery history, notifications metadata, exceptions and audit history. Viewers cannot mutate records, send mail, download operational exports, or reveal raw access codes.

## Run a semester

1. In **Settings**, create the academic semester. Always check the selected semester before importing.
2. In **Import center**, upload the complete approved course/section book requirements. One row per required book per section; different instructors or sections can use different ISBNs.
3. Import the complete **Finance** scholarship student list. University ID is the stable identity within the semester. A later complete Finance file replaces eligibility, but missing students are flagged **missing review** and held; no student history is deleted.
4. In **Publisher requests**, download the **Registrar request**. Staff send it externally. The Registrar completes one row per student-course-section; students taking several courses have several rows.
5. Import the complete **Registrar registration** snapshot. It must include every enrollment to retain. Unlisted enrollments are treated as dropped. A section change is a dropped old section plus an added new section. Missing course/section book requirements appear under **Courses & books** and on the dashboard.
6. Download each publisher's request and send it externally. Code publishers receive outstanding quantities by course/ISBN; Kortext receives the individual student/book rows needed for direct delivery. Repeated downloads of unchanged demand reuse the request history entry. The export is a current outstanding list, not an instruction to place duplicate orders.
7. Upload a code publisher's response. If the file has no publisher column, select the publisher at upload. Valid codes are encrypted, matched by semester + publisher + course + target ISBN, and allocated automatically in demand creation order. Titles/course names remain descriptive; they do not override a mismatching ISBN.
8. Upload Kortext's report. Match by university email and student name, plus validated ISBN; when ISBN is absent, the exact book title after whitespace/case normalization may match a unique eligible demand. Add course and section when necessary to remove ambiguity. No fuzzy matching or invented confirmations occur.
9. Review **Notification outbox** and outstanding stock. In preview mode, administrators can inspect the prepared message but nothing is sent. With SMTP configured, automatic delivery runs after imports/allocations and a scheduled worker completes remaining messages.

## File rules and review

The import center accepts `.xlsx` and UTF-8 `.csv`. Convert legacy `.xls` files to `.xlsx`. Excel files must have exactly one worksheet, one header row, no formulas, no merged-cell dependence, and no more than 10,000 data rows. The first nonempty row contains headers. Use the supplied blank workbooks or map differently named columns in the review step.

Format university IDs, sections, ISBNs and access codes as **text before entering data**. The application preserves leading zeroes that are stored in the file; it cannot reconstruct zeroes already removed by Excel. Excel scientific notation student IDs are rejected. Hyphens/spaces in ISBNs are removed, checksums are validated, and ISBN-10 is converted to ISBN-13.

Every nonempty row is checked. Any invalid row blocks the entire import; correct the file and re-upload. No partial valid subset is silently committed. Identical rows are deduplicated; conflicting duplicate identities or reused access codes with different details are rejected.

| File | Required columns |
|---|---|
| Requirements | course_code, course_name, section, instructor, book_title, isbn, publisher |
| Finance | university_id, student_name, email |
| Registration | university_id, student_name, email, course_code, section |
| Codes | publisher (or choose at upload), course_code, course_name, book_title, isbn, access_code |
| Kortext | student_name, email, book_title; isbn strongly preferred; course_code and section optional only when the match is unique |

Requirements, Finance and registration are **complete replacement snapshots**. Codes and Kortext are incremental responses. Empty files are rejected to prevent accidental mass changes. Identical current snapshots do nothing. A deliberately uploaded older snapshot with different current contents becomes a new revision; check its scope carefully. Previously allocated codes and prior notifications remain unique even when files overlap or students re-enroll.

## Interpret the statuses

- **Allocated**: one code is reserved for one student's demand. It does not mean the student received an email.
- **Queued**: notification is waiting. In preview mode it stays local.
- **Sent**: the SMTP server accepted the notification, or an administrator recorded evidence of that acceptance. It is not proof of inbox delivery, opening or activation.
- **Provider confirmed**: Kortext reported delivery to the student account. The university notification is tracked separately. Kortext also sends its own message externally.
- **Not verified**: student activation remains unknown; no Blackboard or publisher activity is inferred.
- **On hold**: registration, eligibility or the approved requirement changed; past transactions remain visible.
- **Failed**: a pre-submission mail step failed. Correct configuration and queue a retry without reallocating.
- **Uncertain / sending**: the delivery result may be unknown. Check the mail provider and worker before retrying to avoid a duplicate message.

Code emails include the course, section, book, ISBN, code and instructions: **Blackboard > course > publisher deep link integrated using LTI > enter code**. There is no direct Blackboard integration.

## Finance omissions and changes

Filter **Students** by **missing review**, open the student, and record either restoration of eligibility or confirmed removal with a reason. A later Finance snapshot including the student can restore eligibility. Earlier fulfillment remains visible.

If a student drops or changes a course/section after a code notification was sent, a **Finance referral** is created. Export referrals in **Exceptions**, then send the file to Finance externally. It includes student/course/book/ISBN, code-email send time, reason and referral status, without raw access codes. Record the referral and Finance acknowledgement. The application does not issue invoices, calculate charges or collect payment; Finance makes those decisions.

Unsent allocations are retained as reserved history and never recycled automatically. If a student's eligibility returns, a still-valid original allocation is reused rather than creating another code.

## Kortext refunds

A registration/requirement removal after a Kortext delivery creates a refund review. Record **refund requested** only after staff have requested it externally. Record **refund confirmed** only after provider confirmation and include a reference. The original delivery remains in the student's history. Confirmation clears the current delivery state; if the student becomes eligible again, a new provisioning cycle is required.

## Instructor edition incidents

1. In **Exceptions**, select the course/section/book, describe the mismatch, and create the incident. Affected students with allocated codes are linked automatically.
2. Record the instructor's external decision: change the platform book, or return and replace codes. There is no instructor account and the system does not change the publisher's platform itself.
3. For a platform change, record the external confirmation to resolve the incident.
4. For replacement, enter the instructor-approved replacement ISBN. Earlier code allocations become **return requested**, and their history is preserved. Import the new codes; the system allocates replacement codes to the same still-eligible students and prepares replacement messages.
5. Record publisher confirmation of old-code returns separately. The system never recycles returned codes.
6. Resolve after recording confirmation of the remedy. Still-eligible affected students must have sent replacement notifications, and old-code returns must be confirmed. Students no longer eligible do not receive a new replacement code.

New demand created after a replacement decision uses the recorded replacement ISBN. A future independent edition change should be represented by a corrected requirements snapshot or a new incident, preserving the earlier decision history.

## Audit and privacy

Student pages show enrollment changes, demand, code versions, delivery/refund history, notification metadata and relevant audits. The audit trail records actor, UTC time, action, reference and necessary decision notes. Do not paste access codes, passwords or unnecessary sensitive information into free-text case notes. Raw codes are kept in encrypted inventory and protected notification previews, not routine request or Finance exports.