Heratio Help Center article. Category: Technical.

Heratio Library System Technical Manual

Plugin: ahgLibraryPlugin v2.0.0 Framework: Heratio (atom-framework v2.8.2) Author: The Archive and Heritage Group (Pty) Ltd Date: 2026-03-08

1. Architecture Overview

1.1 Plugin Structure

The ahgLibraryPlugin implements a full Integrated Library System (ILS) within Heratio. It extends the archival platform with circulation, cataloging, acquisitions, serials, interlibrary loan, and public access catalog (OPAC) capabilities.

ahgLibraryPlugin/
  config/
    ahgLibraryPluginConfiguration.class.php   # Plugin bootstrap, route registration
  database/
    install.sql                                # Base schema + seed data
    migration_full_library.sql                 # Full ILS migration (18 tables)
  lib/
    Commands/
      ProcessCoversCommand.php                 # Framework CLI command
    Model/
      LibraryItem.php                          # Value object / DTO
    Repository/
      LibraryRepository.php                    # Query layer for library_item
      IsbnLookupRepository.php                 # ISBN cache + audit
      SubjectAuthorityRepository.php           # LCSH subject authority queries
    Service/
      LibraryService.php                       # Core cataloging logic
      CirculationService.php                   # Checkout / checkin / renew
      PatronService.php                        # Patron CRUD + validation
      HoldService.php                          # Hold queue management
      FineService.php                          # Fines + payments
      AcquisitionService.php                   # Purchase orders + budgets
      SerialService.php                        # Subscriptions + issue tracking
      ILLService.php                           # Interlibrary loan workflows
      OpacService.php                          # Public catalog search + self-service
      MarcService.php                          # MARC 21 import/export
      BookCoverService.php                     # ISBN cover image proxy
      IsbnMetadataMapper.php                   # ISBN metadata normalization
      SubjectSuggestionService.php             # NER-based subject suggestions
      WorldCatService.php                      # WorldCat API integration
    helper/
      BookCoverHelper.php                      # Template helper for covers
    task/
      libraryCoverProcessTask.class.php        # Symfony CLI task wrapper
  modules/
    library/          # Cataloging: browse, view, edit, ISBN lookup, providers
    opac/             # Public access catalog: search, item detail, holds, account
    circulation/      # Checkout, checkin, renew, overdue, loan rules
    patron/           # Patron registration, view, suspend, reactivate
    acquisition/      # Purchase orders, order lines, receiving, budgets
    serial/           # Subscription management, issue check-in, claims
    ill/              # Interlibrary loan requests, status transitions
    isbn/             # ISBN lookup, test, statistics
    libraryReports/   # Library reporting dashboard
  web/                # Static assets (CSS, JS)

1.2 Symfony 1.x Integration

The plugin integrates with Heratio's Symfony 1.x framework through ahgLibraryPluginConfiguration:

• Event listeners: Connects to routing.load_configuration for route registration and context.load_factories for helper loading.
• Module enablement: Registers nine modules (library, isbn, libraryReports, opac, circulation, patron, acquisition, serial, ill) via sfConfig::set('sf_enabled_modules', ...).
• Route registration: Uses the framework's RouteLoader class to prepend routes. Routes are added in reverse priority order because prependRoute places each route at the front of the routing table.

1.3 Service Layer Pattern

All services follow the singleton pattern with require_once loading (necessary because Symfony 1.x does not autoload namespaced plugin classes):

class CirculationService
{
    protected static ?CirculationService $instance = null;

    public static function getInstance(): self
    {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        return self::$instance;
    }
}

Every service initializes a Monolog RotatingFileHandler writing to {sf_log_dir}/library.log with 30-day retention. All database operations use Laravel Query Builder (Illuminate\Database\Capsule\Manager as DB).

1.4 Dependencies

• Required: ahgCorePlugin (framework integration)
• Optional integrations: ahgHeritageAccountingPlugin (GRAP 103 asset tracking), ahgAIPlugin (NER-based subject suggestions), ahgPreservationPlugin (format identification)

2. Database Schema

The library system uses 18 tables. All tables use InnoDB with utf8mb4_unicode_ci collation. Status/type fields reference ahg_dropdown values via the ahg_dropdown_column_map table.

2.1 library_item (80 columns)

The core bibliographic record, linked 1:1 to Heratio's information_object.

Indexes: information_object_id (unique implicit), isbn, issn, call_number, barcode.

2.2 library_item_creator

Links creators (authors, editors, etc.) to library items.

2.3 library_item_subject

Subject headings with LCSH authority integration.

2.4 library_copy

Individual physical copies of a library item.

Indexes: uk_barcode (UNIQUE), idx_item, idx_status, idx_branch, idx_accession.

2.5 library_patron

Library borrower records.

2.6 library_checkout

Circulation transactions.

Indexes: idx_copy, idx_patron, idx_status, idx_due, idx_checkout_date.

2.7 library_hold

Patron reservation queue.

Indexes: idx_queue (library_item_id, queue_position).

2.8 library_fine

Fees, penalties, and payment records.

2.9 library_loan_rule

Per-material-type lending policies.

Unique key: uk_type_patron (material_type, patron_type). Seed data includes 11 default rules for monograph, serial, volume, issue, article, manuscript, map, pamphlet, score, electronic, and chapter.

2.10 library_order

Purchase orders.

2.11 library_order_line

Individual line items on a purchase order.

2.12 library_budget

Fund allocation for acquisitions.

Unique key: uk_code_year (budget_code, fiscal_year).

2.13 library_subscription

Serial/periodical subscription tracking.

2.14 library_serial_issue

Individual issue tracking for serials.

2.15 library_ill_request

Interlibrary loan requests (borrow and lend).

2.16 library_settings

Plugin-specific key/value configuration.

2.17 library_subject_authority

Controlled subject heading vocabulary with LCSH integration.

Indexes: UNIQUE uk_heading (heading_normalized, heading_type, source), FULLTEXT ft_heading (heading).

2.18 library_entity_subject_map

Bridges NER-extracted entities to subject authority records.

3. Service Layer

3.1 CirculationService

Core circulation engine handling checkout, checkin, and renewal workflows.

Key methods:

Transaction handling: Checkout and checkin operations use DB::connection()->beginTransaction() with try/catch rollback to ensure atomicity across multiple table updates.

Loan rule fallback chain:

1. Exact: material_type='monograph' AND patron_type='student'
2. Material default: material_type='monograph' AND patron_type='default'
3. Global default: material_type='default' AND patron_type='default'

3.2 PatronService

Patron lifecycle management.

Fine threshold: Configurable via library_settings table (fine_block_threshold key, default 10.00). Patrons with outstanding fines at or above this amount are blocked from borrowing.

3.3 HoldService

Hold queue management. Holds target items (not copies) -- the system assigns a copy at fulfillment.

Auto-promotion: When a copy is returned (via CirculationService::checkin), the processHoldQueue method marks the next pending hold as 'ready' with a 7-day pickup window.

3.4 FineService

Fine creation, payments, waivers, and daily batch processing.

Fine calculation: days_overdue * fine_per_day, capped at fine_cap from the applicable loan rule. Fines are created at checkin time; the daily batch updates amounts for items still checked out.

3.5 AcquisitionService

Purchase order and budget management.

Order status logic: Automatically computed from line statuses -- all received = 'received', any received = 'partial', otherwise 'pending'.

3.6 SerialService

Subscription and issue management.

Frequency mapping: The getFrequencyDays() method converts named frequencies (daily=1, weekly=7, monthly=30, quarterly=91, annual=365, etc.) to day counts for issue generation.

3.7 ILLService

Interlibrary loan workflow in both directions.

Status flow (borrowing): requested -> approved -> shipped -> received -> in_use -> returned Status flow (lending): requested -> approved -> shipped -> returned

3.8 OpacService

Public-facing catalog search and patron self-service.

Publication filter: All public queries join status table filtering type_id=158 (publication status) and status_id=160 (published). Draft and unpublished items are excluded from OPAC results.

3.9 MarcService

MARC 21 import and export via MarcXML format.

Import (importMarcXml):

1. Parses MarcXML with namespace handling (http://www.loc.gov/MARC21/slim)
2. Extracts bibliographic data using the MARC_MAP constant (20+ field mappings)
3. Detects material type from MARC leader (position 6-7)
4. Extracts creators from tags 100/110 (primary) and 700/710 (contributors)
5. Extracts subjects from tags 600-655 with source detection from indicator 2
6. Deduplicates by ISBN (updates existing records)
7. Creates object -> information_object -> information_object_i18n -> slug -> status -> library_item chain for new records

Export (exportMarcXml):

• Generates compliant MarcXML with leader, 008 control field, and all mapped data fields
• Builds leader based on material type (am=monograph, as=serial, em=map, cm=score, tm=manuscript)
• Writes creators, subjects, and all bibliographic fields as MARC data fields with proper indicators

MARC field mapping (excerpt):

4. Modules

4.1 library (Cataloging)

Primary catalog management interface.

4.2 opac (Public Access Catalog)

Public-facing search and self-service.

4.3 circulation

Staff circulation desk.

4.4 patron

Patron management (staff).

4.5 acquisition

Acquisitions and budgets (staff).

4.6 serial

Serial subscription management.

4.7 ill (Interlibrary Loan)

ILL request management.

4.8 isbn

ISBN utility module.

4.9 libraryReports

Library reporting dashboard.

5. Routes

All routes are registered in ahgLibraryPluginConfiguration::addRoutes() using RouteLoader. Routes are organized into 8 groups with a total of 46 routes.

Library Routes

ISBN Routes

OPAC Routes

Circulation Routes

Patron Routes

Acquisition Routes

Serial Routes

ILL Routes

6. Configuration

6.1 ahgLibraryPluginConfiguration.class.php

class ahgLibraryPluginConfiguration extends sfPluginConfiguration
{
    public static $summary = 'Library & Bibliographic Cataloging';
    public static $version = '2.0.0';
    public static $libraryLevelIds = [1700, 1701, 1702, 1703, 1704];
}

The $libraryLevelIds array holds term IDs for library-specific levels of description (Book, Monograph, Periodical, Journal, Manuscript). These are used by ahgDisplayPlugin for sector detection.

6.2 Module Security

The circulation, acquisition, serial, and ill modules have security.yml configurations requiring authentication. The opac module has no security requirements (public access), though the account and hold actions check for authenticated patrons at the action level.

6.3 Dropdown Taxonomies

The migration seeds 14 dropdown taxonomies into ahg_dropdown:

7. Integration Points

7.1 Heratio information_object

Every library item links to an Heratio information_object via library_item.information_object_id. The MARC import creates the full Heratio object chain:

object (class_name='QubitInformationObject')
  -> information_object (parent_id=1, repository_id)
  -> information_object_i18n (title, culture='en')
  -> slug (object_id, slug)
  -> status (type_id=158, status_id=159=Draft or 160=Published)

This integration means library items appear in Heratio's standard browse/search alongside archival descriptions. The ahgDisplayPlugin auto-detects library-sector items based on level of description terms.

7.2 Publication Status

The OPAC enforces publication status filtering using Heratio's status table:

• type_id = 158 = Publication status type
• status_id = 159 = Draft (excluded from OPAC)
• status_id = 160 = Published (visible in OPAC)

7.3 Heritage Accounting (GRAP 103 / IPSAS 45)

The library_item table includes 18 heritage accounting columns for South African public sector compliance:

• Acquisition tracking: method, date, cost, currency
• Valuation: replacement_value, insurance_value/policy/expiry, valuation_date/method/notes
• Asset classification: heritage_asset_id (FK to heritage_asset table), asset_class_code, recognition_status
• Provenance: donor_name, donor_restrictions
• Condition: condition_grade, conservation_priority

The FineService::createLostItemFine() method uses replacement_value for charging lost item fees, falling back to acquisition_cost.

7.4 Subject Authority with LCSH

The library_subject_authority table provides a local cache of controlled subject headings with:

• LCSH identifiers and URIs
• Suggested Dewey and LCC classification numbers
• Hierarchical relationships (broader/narrower/related terms as JSON)
• Usage tracking for autocomplete ranking

The library_entity_subject_map table bridges NER-extracted entities to subject authorities, enabling AI-assisted subject heading assignment via SubjectSuggestionService.

8. CLI Commands

library:process-covers

php symfony library:process-covers [--limit=N] [--force]

Implemented in lib/task/libraryCoverProcessTask.class.php and lib/Commands/ProcessCoversCommand.php.

Processes library items with ISBN but no cover_url:

1. Queries library_item for records with ISBN and NULL cover_url
2. Fetches cover images from configured ISBN providers (Open Library, Google Books, etc.)
3. Updates cover_url and cover_url_original columns
4. Respects rate limits on external APIs

Options:

• --limit=N : Process at most N items (default: all)
• --force : Re-fetch covers even if cover_url is already set

9. Key Patterns

9.1 Singleton Services with require_once

Symfony 1.x does not autoload namespaced plugin classes. Services are loaded explicitly:

$pluginPath = sfConfig::get('sf_plugins_dir') . '/ahgLibraryPlugin/lib/Service/';
require_once $pluginPath . 'PatronService.php';
require_once $pluginPath . 'CirculationService.php';

$circService = CirculationService::getInstance();

9.2 Laravel Query Builder

All data access uses Laravel's query builder via the framework-initialized Capsule:

use Illuminate\Database\Capsule\Manager as DB;

$item = DB::table('library_item')
    ->where('isbn', $isbn)
    ->first();

DB::table('library_checkout')->insertGetId([...]);

9.3 Monolog Logging

All services log to a shared rotating log file:

$this->logger = new Logger('library.circulation');
$logPath = \sfConfig::get('sf_log_dir', '/tmp') . '/library.log';
$this->logger->pushHandler(new RotatingFileHandler($logPath, 30, Logger::DEBUG));

Log channels: library, library.circulation, library.patron, library.hold, library.fine, library.acquisition, library.serial, library.ill, library.opac, library.marc.

9.4 AhgController Base Class

Module actions extend AhgController (from ahgCorePlugin) for common functionality:

• Authentication and ACL checks
• JSON response helpers
• Error handling
• Template variable assignment

9.5 Barcode Generation

Patron and copy barcodes are auto-generated with uniqueness checks:

• Patron: P + 6 random digits (e.g., P384729)
• Copy: C + 7 random digits (e.g., C2847391)
• Order: PO-YYYY-NNNN sequential (e.g., PO-2026-0042)

9.6 Transaction Safety

Multi-table operations (checkout, checkin) use explicit transactions:

DB::connection()->beginTransaction();
try {
    // Multiple table updates
    DB::connection()->commit();
} catch (\Exception $e) {
    DB::connection()->rollBack();
    return ['success' => false, 'error' => $e->getMessage()];
}

9.7 Cron Jobs

Two operations should be scheduled as daily cron jobs:

• FineService::generateDailyOverdueFines() -- recalculates accumulating overdue fines
• HoldService::expireOverdueHolds() -- expires 'ready' holds past their pickup window and promotes the next patron in queue

Appendix: Entity Relationship Summary

information_object 1----1 library_item 1----* library_item_creator
                                        1----* library_item_subject ----* library_subject_authority
                                        1----* library_copy 1----* library_checkout ----* library_fine
                                        1----* library_hold
                                        1----* library_subscription 1----* library_serial_issue

library_patron 1----* library_checkout
               1----* library_hold
               1----* library_fine
               1----* library_ill_request

library_order 1----* library_order_line
library_budget (standalone, linked by budget_code)
library_entity_subject_map *----1 library_subject_authority
library_settings (standalone key/value)
library_loan_rule (standalone policy table)