# Robertson Library ILL Forms Module

## Introduction

This Drupal module provides a front-end Interlibrary Loan (ILL) request form for
the UPEI Robertson Library. Patrons fill out a two-step form with bibliographic
information and authentication details, and the request is submitted to
**RapidILL** for processing.

**Branch guide:**

- `1.x` -- Relais integration (legacy)
- `3.x` -- RapidILL integration (current)

## How It Works

1. **Step 1 -- Bibliographic Information:** The patron selects a genre
   (article, book, or chapter) and enters citation details. A DOI lookup button
   can auto-populate fields from CrossRef.
2. **Step 2 -- Patron Authentication:** The patron provides their name, UPEI
   ID, email, department, and patron type. The module verifies the patron
   against the Evergreen ILS REST API by matching the provided surname to the
   `family_name` on file.
3. **Submission:** On successful authentication the request is sent to RapidILL
   and logged to the `upei_roblib_ill_request` database table.
4. **Confirmation:** The patron is redirected to a confirmation page with the
   RapidILL request number.

OpenURL parameters and DOIs can be passed in via query string so the form can be
pre-populated from discovery tools such as EBSCO or Google Scholar.

## Requirements

- Drupal 9 or 10
- An Evergreen ILS instance with the `osrf-gateway-v1` REST API accessible
- A RapidILL account (username, password, Rapid code, and branch name)
- A CrossRef OpenURL PID (for DOI lookups)

## Installation

Install as you would any Drupal module. No additional dependencies are required.

## Configuration

Navigate to **Administration > Settings > Roblib ILL**
(`/admin/settings/roblibill`) and configure the following sections:

### General

| Setting              | Description                                           |
|----------------------|-------------------------------------------------------|
| ILL Library Symbol   | Your Relais/RapidILL library symbol                   |
| OpenURL PID          | Your CrossRef OpenURL PID for DOI resolution          |
| Contact Email        | Email shown on the confirmation page (e.g. ill@upei.ca) |
| Contact Phone        | Phone number shown on the confirmation page           |

### Evergreen ILS

| Setting                  | Description                                                  |
|--------------------------|--------------------------------------------------------------|
| Evergreen API URL        | Base URL of your Evergreen server (e.g. `https://catalogue.example.com`) |
| Evergreen Staff Username | Staff account used for REST API authentication               |
| Evergreen Staff Password | Password for the staff account                               |

The module authenticates against Evergreen by calling
`open-ils.auth.authenticate.init` / `open-ils.auth.authenticate.complete` to
obtain a session token, then retrieves the patron record with
`open-ils.actor.user.retrieve` and compares the `family_name` field to the
surname provided by the user.

### RapidILL

| Setting              | Description                               |
|----------------------|-------------------------------------------|
| RapidILL Username    | Your RapidILL API username                |
| RapidILL Password    | Your RapidILL API password                |
| RapidILL Rapid Code  | Your library's Rapid code                 |
| RapidILL Branch Name | Your library branch name (e.g. Main)      |

## Routes

| Path                            | Description                  |
|---------------------------------|------------------------------|
| `/admin/settings/roblibill`     | Module settings form         |
| `/upei/roblib/ill/{parameters}` | ILL request form             |
| `/upei/roblib/ill/finished`     | Post-submission confirmation |

## Views Integration

The module exposes the `upei_roblib_ill_request` table to Drupal Views, so
administrators can build custom reports and lists of submitted ILL requests.

## Maintainers / Sponsors

- UPEI Robertson Library