AtoM Heratio Research Portal — Training Manual

Plugin: ahgResearchPlugin v3.3.0 Platform: AtoM Heratio (AtoM 2.10 + AHG Framework v2.8.2) Author: The Archive and Heritage Group (Pty) Ltd Last Updated: May 2026

Table of Contents

1. Overview
2. Getting Started
3. Dashboard
4. Researcher Registration & Profile
5. Reading Room & Bookings
6. Collections
7. Saved Searches & Discovery
8. Annotations & Notes
9. Annotation Studio (W3C Web Annotations)
10. Bibliographies & Citations
11. Research Projects
12. Collaboration & Workspaces
13. Research Journal
14. Research Reports
15. Hypotheses
16. Source Assessment & Trust Scoring
17. Knowledge Graph & Assertions
18. Snapshots & Reproducibility
19. AI Extraction & Validation Queue
20. Entity Resolution
21. Visualization Tools
22. Reproduction Requests
23. Request Lifecycle & SLA
24. Material Retrieval & Custody
25. Accessibility
26. Rights & Access Policies (ODRL)
27. RO-Crate & DOI Minting
28. Notifications
29. REST API & API Keys
30. ORCID Integration
31. Institutional Sharing
32. Audit Trail
33. Administration
34. Database Reference
35. Troubleshooting
36. Studio — Grounded AI Artefact Generator (NEW v3.3.0)
37. Citation Hover Popovers (NEW v3.3.0)
38. Researcher Notebooks (NEW v3.3.0)
39. Cross-Fonds Reasoning Queries (NEW v3.3.0)
40. Research Analytics Dashboard (NEW v3.3.0)
41. Live Collaboration Panel (NEW v3.3.0)
42. Per-Record Citation Manager Export (NEW v3.3.0)
43. ORCID Works Push & Pull (NEW v3.3.0)
44. Mobile Shell (PWA) (NEW v3.3.0)
45. Offline Mode & Sync (NEW v3.3.0)

1. Overview

The AtoM Heratio Research Portal is an enterprise-grade research support platform built into the AtoM archival management system. It provides a complete environment for researchers to discover, analyze, annotate, and publish findings from archival collections.

Key Capabilities

User Roles

2. Getting Started

Accessing the Portal

Navigate to /research on your AtoM Heratio instance (e.g., https://psis.theahg.co.za/research).

First-Time Setup

1. Register — Click "Register as Researcher" or navigate to /research/register
2. Complete Profile — Fill in personal details, institution, research interests
3. Wait for Approval — An admin must approve your registration
4. Receive Confirmation — Once approved, you can access all research features
5. Connect ORCID (optional) — Link your ORCID iD for scholarly identification

Navigation Structure

Research Portal (/)
├── Dashboard (/research)
├── Profile (/research/profile)
│   └── API Keys (/research/profile/api-keys)
├── Bookings (/research/bookings)
│   └── Book (/research/book)
├── Collections (/research/collections)
│   └── View Collection (/research/collection/:id)
├── Saved Searches (/research/saved-searches)
├── Annotations (/research/annotations)
│   └── Annotation Studio (/research/annotation-studio/:object_id)
├── Bibliographies (/research/bibliographies)
│   └── View Bibliography (/research/bibliography/:id)
├── Projects (/research/projects)
│   └── View Project (/research/project/:id)
├── Workspaces (/research/workspaces)
│   └── View Workspace (/research/workspaces/:id)
├── Journal (/research/journal)
├── Reports (/research/reports)
├── Reproductions (/research/reproductions)
├── Notifications (/research/notifications)
└── Invitations (/research/invitations)

3. Dashboard

URL: /research

The dashboard is your home base. It displays:

• Today's Bookings — Upcoming reading room sessions
• Pending Requests — Material requests awaiting fulfillment
• Recent Activity — Your latest actions (annotations, collections, searches)
• Recent Notes — Last 5 annotations/notes
• Recent Journal — Last 5 journal entries
• Search Alerts — Saved searches with new results
• Pending Invitations — Project/workspace invitations requiring action
• Active Projects — Projects you're contributing to
• Unread Notifications — Count of unread notifications

Quick Actions from Dashboard

• Create a booking
• Start a new project
• Browse collections
• View notifications

4. Researcher Registration & Profile

Registration

URL: /research/register (authenticated) or /research/register-researcher (public)

Required Fields:

• First name, Last name
• Email address
• ID type (National ID, Passport, Driver's License, Student Card, Other)
• ID number

Optional Fields:

• Title (Mr, Mrs, Ms, Dr, Prof)
• Phone
• Affiliation type (Independent, Academic, Government, Corporate, NGO)
• Institution, Department, Position
• Student ID
• Research interests (free text)
• Current project description
• ORCID iD

Process Flow:

Registration → Pending Status → Admin Review → Approved/Rejected
                                                    ↓
                                              Access Request Created
                                              (Internal clearance level)

On registration, an access request is automatically created requesting "Internal" clearance level. The admin can approve or reject through the researcher management interface.

Rejection with Audit Trail

When a researcher is rejected:

1. All data is copied to research_researcher_audit table
2. The main record is deleted from research_researcher
3. The user account is deactivated (user.active = 0)
4. The access request is set to "denied" with the rejection reason
5. The email/user can re-register in the future

Profile Management

URL: /research/profile

Researchers can update their profile information at any time. Changes are audit-logged.

Researcher Types

Admins can configure researcher types that control access limits:

Verification System

Researchers may need to verify their identity:

Verification Types:

• ID document verification
• Institutional affiliation verification
• Student enrollment verification
• Professional qualification verification

Process: Upload verification documents → Admin reviews → Verified/Rejected

Verified researchers get enhanced access. Verifications can have expiry dates (e.g., student enrollment verification expires annually).

Credential Renewal

URL: /research/renewal

When a researcher's access expires (based on their type's expiry_months), they can request renewal through this page.

5. Reading Room & Bookings

Creating a Booking

URL: /research/book

1. Select a reading room from the available rooms
2. Choose a date (limited by your researcher type's max_booking_days_advance)
3. Select start time and end time (limited by max_booking_hours_per_day)
4. Specify purpose of visit (optional)
5. Add notes (optional)
6. Submit — booking status becomes "Pending"

Booking Lifecycle

Pending → Confirmed (by admin) → Checked In → Completed (Checked Out)
   ↓                                              ↓
Cancelled                                    Materials Returned

Material Requests

When viewing a booking, you can add material requests:

1. Search for archival items by title, identifier, or reference number
2. Add items to the booking's material request list
3. Each item gets a status: Requested → Delivered → Returned
4. Material request notes can be added per item

Material request limits are enforced by your researcher type (e.g., 10 items for Registered Researchers, 25 for Heritage Professionals).

Check-In / Check-Out

• Check In (/research/booking/:id/check-in) — Marks arrival time
• Check Out (/research/booking/:id/check-out) — Marks departure, completes booking

Walk-In Visitors

URL: /research/walk-in

For unregistered visitors who walk into the reading room without a booking:

1. Staff records visitor details (name, ID, purpose)
2. Visitor is assigned a temporary seat
3. On departure, staff checks them out
4. Walk-in visitors can later be converted to registered researchers

Seat Assignment

URL: /research/seats

Reading rooms can have mapped seats:

• Seat Map (/research/seats/map) — Visual layout of the room
• Auto-Assign — System selects the best available seat based on preferences
• Manual Assign — Staff selects a specific seat for a researcher

Seat properties: number, label, section, row, position, has_power, has_network, has_lamp, is_accessible, equipment type.

Equipment Booking

URL: /research/equipment

Reading rooms may have bookable equipment:

• Microfilm readers
• Digital scanners
• Laptops
• Magnifying glasses

Book equipment alongside your reading room booking.

Retrieval Queue

URL: /research/retrieval-queue

Staff use this to manage the physical retrieval of materials. The queue is divided into named sub-queues (New, Rush, Retrieval, Transit, Delivery, Curatorial, Return), each with a summary card showing the count of pending requests.

Queue Summary Cards — click any card to filter the table below to that queue.

Per-Request Actions:

• Print Call Slip — open a printable call slip for an individual request
• Checkout — available when status is retrieved or delivered; opens the custody checkout form
• Return — available when status is in_use; opens the custody return/check-in form
• Custody Chain — view the full chain-of-custody history for the linked archival object

Batch Actions (bottom toolbar):

1. Select one or more requests using the checkboxes
2. Update Status — move selected requests to a new status (Requested, Retrieved, Delivered, In Use, Returned, Unavailable) with optional notes
3. Print Selected — print call slips for all selected requests
4. Batch Checkout — open the batch checkout form for selected requests
5. Batch Return — open the batch return form for selected requests

Status Lifecycle:

Requested → Retrieved → Delivered → In Use → Returned
                                       ↓
                                   Unavailable

Location Tracking — the Current Location column updates automatically as requests move through statuses:

• Requested: original shelf location
• Retrieved: "In transit"
• Delivered / In Use: "Reading room"
• Returned: "Return shelf (pending re-shelving)"

Call Slips

URL: /research/call-slips/print

Generate printable call slips for material retrieval. Call slips include:

• Researcher name and booking details
• Item reference number, title, and location
• Date and retrieval schedule

6. Collections

Creating Collections

URL: /research/collections

Collections are personal groupings of archival items for research purposes.

1. Click "Create Collection"
2. Enter name and description
3. Set visibility: Private or Public
4. A unique share token is automatically generated

Adding Items to Collections

There are several ways to add items:

• From browse/search results — Click "Add to Collection" button on any item
• From the collection view — Search and add items
• Via AJAX (/research/ajax/add-to-collection) — Used by the browse interface
• From clipboard — Move clipboard items to a collection

Collection Operations

Finding Aid Export

URL: /research/collection/:id/export/:format

Formats: PDF, DOCX

The finding aid includes:

• Collection metadata (name, description, researcher)
• All items with their archival description fields
• Hierarchical descendants of each item
• Researcher notes per item

7. Saved Searches & Discovery

Saving Searches

When you perform a search in the browse interface, you can save it:

1. Run a search query
2. Click "Save Search"
3. Enter a name and optional description
4. Choose whether to enable alerts

Each saved search automatically receives a Citation ID in the format: QRY-{researcherId}-{searchId}-{hash8}

Example: QRY-12-45-a3b7c9d1

Managing Saved Searches

URL: /research/saved-searches

The saved searches page shows:

Result Diffing

Click the Diff button (exchange icon) to compare current search results against the last snapshot:

• Added — New items matching the query since the last snapshot
• Removed — Items that no longer match
• Unchanged — Items present in both

The diff modal shows:

• Previous count, Current count, Unchanged count
• List of added items with titles
• List of removed items with titles

Result Snapshots

Click the Snapshot button (camera icon) to save the current result set as a baseline:

• Stores all current result IDs in result_snapshot_json
• Updates last_result_count
• Future diffs will compare against this snapshot

Search Alerts

When alerts are enabled on a saved search:

• The system periodically checks for new results
• New result counts appear on the dashboard
• Notification is sent when new items match your query

8. Annotations & Notes

Legacy Annotations

URL: /research/annotations

Basic annotations can be attached to any archival item:

Rich Text Editing

The annotation editor supports:

• Bold, italic, underline, strikethrough
• Headings (H1-H6)
• Ordered and unordered lists
• Blockquotes and code blocks
• Links and images
• Tables

Searching Annotations

Full-text search across all your annotations using MySQL's MATCH...AGAINST:

• Searches title and content fields
• Boolean mode for advanced queries

Exporting Annotations

URL: /research/notes/export/:format

Formats: PDF, DOCX, CSV

9. Annotation Studio (W3C Web Annotations)

Overview

URL: /research/annotation-studio/:object_id

The Annotation Studio provides a standards-compliant annotation interface implementing the W3C Web Annotation Data Model.

Creating Annotations

The right sidebar contains the "Create Annotation" panel:

1. Motivation — Select the purpose:

   • Commenting — General comments
   • Describing — Descriptive annotations
   • Classifying — Classification/categorization
   • Linking — Linking to related resources
   • Questioning — Questions about the content
   • Tagging — Tags/labels
   • Highlighting — Highlights of interest

2. Body Text — Enter the annotation content

3. Visibility — Private, Shared, or Public

4. Click "Create Annotation"

Multi-Target Annotations

After creating an annotation, you can add multiple targets using different selector types:

To add a target:

1. Click "Add Target" on an existing annotation
2. Select the selector type
3. Fill in the selector-specific fields
4. Click "Save Target"

IIIF Import/Export

Import: Click "Import IIIF" to upload a W3C Web Annotation JSON-LD file Export: Click "Export IIIF" to download annotations as a JSON-LD annotation list

The export follows the IIIF Presentation API 3.0 annotation format, compatible with:

• Mirador
• Universal Viewer
• Annona
• Other IIIF-compliant viewers

Promote to Assertion

Each annotation has a "Promote to Assertion" button that converts the annotation into a formal research assertion in the knowledge graph. This creates:

• Subject: the annotated object
• Predicate: annotated_as
• Type: attributive

10. Bibliographies & Citations

Creating Bibliographies

URL: /research/bibliographies

1. Click "Create Bibliography"
2. Enter name and description
3. Optionally link to a project

Adding Entries

There are multiple ways to add bibliography entries:

Manual Entry — Full citation metadata:

• Entry type (book, article, chapter, thesis, website, archival, report, other)
• Title, Authors, Year, Publisher
• Journal, Volume, Issue, Pages
• DOI, ISBN, URL
• Abstract, Notes

From Archive Items — Click "Add to Bibliography" while browsing:

• Automatically extracts title, dates, creators, repository
• Links back to the archival record

Import:

• BibTeX format
• RIS format

Citation Styles

Generate citations in 6 styles:

Exporting Bibliographies

URL: /research/bibliography/:id/export/:format

11. Research Projects

Creating Projects

URL: /research/projects

Fields:

• Title
• Description
• Project type (Individual, Group, Institutional, Grant-funded)
• Institution
• Supervisor (for academic projects)
• Funding source and Grant number
• Ethics approval reference
• Start date and Expected end date
• Status (Active, On Hold, Completed, Archived)
• Visibility (Private, Collaborators, Public)

Project Resources

Attach resources to projects:

• Link archival collections
• Link saved searches
• Add external document references
• Add URL resources
• Move clipboard items to project

Project Milestones

Track project progress with milestones:

• Title and description
• Type: deliverable, ethics, data_collection, analysis, writing, review
• Status: pending, in_progress, completed, overdue
• Due date
• Completion date

Project Activity Log

Every action within a project is logged:

• Collection additions
• Annotation creation
• Assertion changes
• Collaborator joins
• Resource additions

URL: /research/project/:id/activity

Clipboard Integration

The clipboard feature lets you:

1. Add items from browse to your clipboard
2. Move clipboard items to a specific project
3. Pin important clipboard items
4. Add notes to clipboard items

12. Collaboration & Workspaces

Project Collaboration

Inviting Collaborators:

1. Navigate to project → Collaborators tab
2. Click "Invite Collaborator"
3. Search for registered researchers
4. Assign a role: Viewer, Contributor, Editor, Admin

Roles:

Invitation Flow:

Invite Sent → Pending → Accepted/Declined

Workspaces

URL: /research/workspaces

Workspaces are independent collaboration spaces (not tied to a specific project):

1. Create a workspace with name, description, visibility
2. Invite members with roles
3. Attach resources (items, documents, URLs)
4. Start discussions

Discussions

Within workspaces, create threaded discussions:

• Create a new discussion topic
• Reply to existing discussions (nested threading)
• Pin important discussions
• Resolve discussions when concluded

Comments

Comments can be added to:

• Projects
• Reports
• Assertions
• Any entity with a comment thread

Supports markdown formatting and nested replies.

Peer Review

URL: /research/report/:id/review/request

Request peer review on research reports:

1. Select a reviewer from registered researchers
2. Send review request
3. Reviewer receives notification
4. Reviewer submits review with:
   • Rating (1-5)
   • Recommendation (accept, revision, reject)
   • Detailed feedback
   • Private notes (visible only to admin)

13. Research Journal

Overview

URL: /research/journal

The research journal is a chronological log of your research activities, thoughts, and findings.

Creating Entries

URL: /research/journal/new

Fields:

• Entry date
• Title
• Content (rich text)
• Entry type: reflection, observation, methodology, finding, question, other
• Mood/energy (optional)
• Time spent (hours)
• Linked project (optional)
• Related entity (type + ID)
• Tags

Auto-Entries

The system automatically creates journal entries for key actions:

• Saving a search query
• Creating a collection
• Adding annotations
• Completing bookings

Auto-entries are tagged with type auto_* (e.g., auto_search, auto_collection).

Calendar View

The journal page shows a monthly calendar with entry dates highlighted. Click a date to see entries for that day.

Time Tracking

The journal tracks time spent per project, available as a summary:

• Hours per project
• Hours by entry type
• Monthly totals

Exporting

URL: /research/journal/export/:format

Formats: PDF, DOCX, CSV

14. Research Reports

Creating Reports

URL: /research/report/new

Reports are multi-section documents for formal research output.

Report Fields:

• Title
• Type: research_report, literature_review, case_study, methodology, analysis, proposal, finding_aid
• Abstract
• Keywords
• Status: draft, review, final, published
• Linked project

Report Sections

Each report consists of ordered sections:

• Add sections with title and content (rich text)
• Reorder sections via drag-and-drop
• Each section can have its own heading level

Auto-Population

Click "Auto-populate from Project" to automatically generate sections from:

• Project description → Introduction
• Collection items → Sources
• Annotations → Findings
• Bibliographies → References

Templates

Pre-defined templates:

• Research Report (standard academic format)
• Literature Review
• Case Study
• Methodology paper

Exporting Reports

URL: /research/report/:id/export/:format

15. Hypotheses

Overview

URL: /research/hypotheses/:project_id

Hypotheses are formal research propositions that can be tested through evidence.

Creating a Hypothesis

Fields:

• Title
• Description
• Assertion basis (what the hypothesis claims)
• Status: proposed, testing, supported, refuted, inconclusive

Evidence Tracking

For each hypothesis, you can add supporting or opposing evidence:

• Evidence type: supports, contradicts, neutral
• Source reference (object ID, document, URL)
• Confidence score (0-1)
• Notes

Hypothesis Lifecycle

Proposed → Testing → Supported / Refuted / Inconclusive

The evidence timeline shows all evidence added over time, allowing you to track how the hypothesis evolved.

16. Source Assessment & Trust Scoring

Source Assessment

URL: /research/source-assessment/:object_id

Evaluate the trustworthiness and quality of archival sources:

Assessment Criteria:

Additional Fields:

• Assessment methodology (textual description)
• Notes and observations
• Cross-reference sources

Quality Metrics

Automated quality metrics from AI services:

• OCR confidence scores
• Digitization quality
• Metadata completeness
• Format identification confidence

Trust Score Computation

The trust score is computed from:

1. Human assessments (authority, reliability, bias, accuracy)
2. Automated quality metrics (OCR confidence, format ID)
3. Weighted combination with configurable weights

17. Knowledge Graph & Assertions

Overview

The knowledge graph represents structured research claims as subject-predicate-object triples with evidence tracking and conflict detection.

Creating Assertions

URL: /research/assertion/create

An assertion consists of:

Assertion Status

Proposed → Under Review → Verified / Disputed / Withdrawn

Evidence

Each assertion can have multiple pieces of evidence:

• Source type (document, oral_testimony, physical_evidence, digital_record)
• Source ID (reference to archival object)
• Confidence score
• Status: proposed, verified, disputed

Conflict Detection

The system automatically detects conflicting assertions:

• sameAs conflicts with differentFrom
• Contradictory temporal claims
• Inconsistent spatial assertions

URL: /research/assertion/:id/conflicts

Knowledge Graph Visualization

URL: /research/knowledge-graph/:project_id

Interactive D3.js visualization showing:

• Nodes = Entities (actors, objects, places)
• Edges = Assertions (predicates)
• Colors = Assertion status (green=verified, yellow=proposed, red=disputed)

Batch Review

URL: /research/assertion-batch-review/:project_id

Review multiple proposed assertions at once:

• Select assertions to review
• Set new status (verified, disputed, withdrawn)
• Apply to all selected

18. Snapshots & Reproducibility

Creating Snapshots

URL: /research/snapshot/create

Snapshots are immutable captures of a collection's state at a point in time.

From a collection:

1. Navigate to a collection
2. Click "Create Snapshot"
3. The snapshot captures:
   • All item IDs and their metadata
   • Rights state per item
   • Query state and rights state JSON
   • A cryptographic hash of all state

Snapshot Status:

Active → Frozen → Archived

Frozen Snapshots

When a snapshot is frozen:

• It cannot be modified, archived, or deleted
• A frozen_at timestamp is recorded
• A Citation ID is generated: SNAP-{projectId}-{snapshotId}-{shortHash}
• Rights snapshots are captured per item

Hash Verification

Each snapshot has a SHA-256 HMAC hash computed from:

• Snapshot metadata (query_state_json, rights_state_json, metadata_json)
• Each item's metadata_version_json and rights_snapshot_json
• Stable sorting by object_id ASC, object_type ASC

Verify integrity: The system recomputes the hash and compares it to the stored hash. If they match, the snapshot is verified as unmodified.

Comparing Snapshots

URL: /research/snapshot/compare

Compare two snapshots side-by-side:

• Items added since snapshot A
• Items removed since snapshot A
• Items present in both

Snapshot Citation

Use the citation ID (e.g., SNAP-5-23-a1b2c3d4) to reference a specific state of a collection in publications, ensuring reproducibility.

19. AI Extraction & Validation Queue

Extraction Jobs

URL: /research/extraction-jobs/:project_id

Create AI extraction jobs to process archival items:

Creating a Job

1. Select a project and optionally a collection
2. Choose the extraction type
3. Configure parameters (e.g., language, model)
4. Submit — job runs in the background

Job Status

Pending → Running → Completed / Failed

Progress tracking shows: items processed / total items.

Extraction Results

Each extraction produces results with:

• Result type (entity, summary, translation, transcription, form_field, face)
• Extracted data (JSON)
• Confidence score (0-1)
• Model version
• Input hash (for reproducibility)

Validation Queue

URL: /research/validation-queue

The validation queue is where human reviewers approve, modify, or reject AI extraction results.

Stats Bar: Shows counts of Pending, Accepted, Rejected results and the average confidence score.

Filters:

• Status: Pending, Accepted, Rejected, Modified, All
• Result Type: entity, summary, translation, transcription, form_field, face
• Extraction Type: OCR, NER, summarize, translate, spellcheck, face_detection, form_extraction
• Minimum Confidence: 0.00 - 1.00

Table Columns:

• Object (title or ID)
• Extraction type
• Result type
• Model version
• Confidence (with color-coded progress bar)
• Reviewer name
• Status badge

Actions:

• Preview — View the full extracted data as formatted JSON
• Accept — Approve the result
• Edit & Accept — Modify the JSON data, then accept
• Reject — Reject with a reason

Bulk Operations:

• Select multiple items with checkboxes
• Bulk Accept — Accept all selected
• Bulk Reject — Reject all selected (with reason)

20. Entity Resolution

Overview

URL: /research/entity-resolution

Entity resolution identifies and links duplicate or related entities across archival collections. For example, recognizing that "J. Smith" in Collection A and "John Smith" in Collection B are the same person.

Proposing Matches

Click "Propose Match" to open the proposal form:

Fields:

• Entity A: Type (actor/information_object/repository) and ID
• Entity B: Type and ID
• Relationship type:
  • sameAs — Identical entities (default)
  • relatedTo — Associated entities
  • partOf — Hierarchical relationship
  • memberOf — Group membership
• Match method: Manual, Name Similarity, Identifier Match, Authority Record
• Confidence score (0-1)
• Notes
• Evidence (one per line): source_type | source_id | note

Automatic Candidate Finding

URL: /research/entity-resolution/candidates?entity_type=actor&entity_id=123

The system can find potential matches automatically:

1. Enter an entity type and ID
2. The system searches for similar entities using name similarity
3. Results are ranked by similarity score (0-1)
4. Only candidates above 30% similarity are shown

For actors, similarity is computed using PHP's similar_text() function on the authorized form of name.

Reviewing Proposals

The entity resolution table shows:

Conflict Detection

Before accepting a match, click the Conflict Check button (warning triangle):

• Checks for existing assertions that contradict the proposed relationship
• For example, a differentFrom assertion would conflict with a sameAs proposal
• Shows "Safe to accept" if no conflicts found

sameAs Assertion Creation

When a sameAs match is accepted:

1. An assertion is automatically created: Entity A sameAs Entity B
2. The assertion includes the resolution evidence
3. The assertion appears in the knowledge graph

Entity Link Network

Use getEntityLinks() to see all accepted resolutions for an entity — its full sameAs/relatedTo network.

21. Visualization Tools

Timeline Builder

URL: /research/timeline/:project_id

Create chronological timelines of research events:

Event Fields:

• Title, Description
• Start date, End date
• Event type (creation, modification, transfer, destruction, discovery, other)
• Related entity (type + ID)
• Media URL (optional image/video)

Features:

• Auto-populate from a collection's date metadata
• Interactive timeline visualization
• Add/edit/delete events
• Link events to archival items

Geographic Map

URL: /research/map/:project_id

Plot research locations on an interactive map:

Point Fields:

• Title, Description
• Latitude, Longitude
• Point type (origin, destination, event, discovery, repository, other)
• Related entity (type + ID)
• Date (optional)

Features:

• Add points manually or from archival metadata
• Bounding box search for nearby items
• Interactive map with markers and popups
• Link points to archival items

Network Graph

URL: /research/network-graph/:project_id

Visualize entity relationships as a network:

Features:

• D3.js force-directed graph
• Nodes represent entities (actors, objects, repositories)
• Edges represent relationships (creator, subject, location, etc.)
• Filter by entity type and relationship type
• Export to GEXF format (compatible with Gephi)

Knowledge Graph

URL: /research/knowledge-graph/:project_id

Dedicated visualization of research assertions:

• Subject → Predicate → Object relationships
• Color-coded by assertion status
• Interactive node exploration
• Filter by assertion type and status

22. Reproduction Requests

Creating Requests

URL: /research/reproduction/new

Request digital reproductions of archival materials:

Request Fields:

• Purpose of reproduction
• Intended use (personal, publication, exhibition, commercial)
• Required format (digital scan, photocopy, photograph)
• Quality requirements (72dpi, 150dpi, 300dpi, 600dpi)
• Delivery method (download, email, post)
• Special instructions

Adding Items

Add items to the reproduction request:

• Search for archival items
• Specify pages/sections needed
• Add per-item notes

Request Lifecycle

Draft → Submitted → Pending Triage → Triage Approved → In Fulfilment → Delivered → Closed
                                          ↓
                                    Triage Denied
                                          ↓
                                    Needs Information (researcher contacted)

Triage — every incoming request goes through a triage step where staff can approve, deny, or request more information from the researcher before work begins. See Section 23: Request Lifecycle & SLA for full details.

Pricing

Costs are calculated based on:

• Item count and type
• Quality/resolution
• Format requested
• Rush processing (if available)

File Delivery

Once completed:

• Files are uploaded by staff
• Each file gets a unique download token
• Researchers access downloads at /research/reproduction/download/:token
• Download is logged for audit purposes

23. Request Lifecycle & SLA

Requests Dashboard

URL: /research/requests-dashboard

The combined requests dashboard shows all material and reproduction requests in a single view with SLA status indicators.

Summary Cards:

• Total material requests
• Total reproduction requests
• Overdue requests (past SLA due date)

Table Columns:

• ID, Type (Material/Reproduction), Title, Researcher, Status, Priority, SLA Due Date, Assigned To

SLA Badges:

• Green: on track (more than 3 days remaining)
• Yellow/Warning: approaching deadline (3 days or fewer)
• Red/Danger: overdue (past SLA due date)

Triage

URL: /research/request/:id/triage/:type

Every new request must go through triage before processing begins. Triage captures:

Triage Decisions:

• Approve — request is valid and can proceed to fulfilment; SLA timer starts
• Deny — request is rejected with a reason (e.g., restricted material, insufficient justification)
• Needs Information — researcher is contacted for clarification before a decision

Triage Form Fields:

• Decision (approve / deny / needs information)
• Notes (required for deny and needs-information decisions)

When a request is triaged as "approved", the system automatically computes the SLA due date based on the configured policy (default: 10 working days). A workflow event is emitted for the audit trail.

Assignment

URL: /research/request/:id/assign/:type

Staff can assign requests to specific team members for fulfilment. Assignment:

• Records who is responsible for the request
• Emits a workflow event for the audit trail
• Visible on the requests dashboard

Correspondence

URL: /research/request/:id/correspond/:type

A built-in correspondence thread between staff and researchers, attached to each request.

Features:

• Threaded view with staff messages (blue) and researcher messages (green)
• Internal notes visible only to staff (yellow highlight, lock icon)
• Quick action buttons for triage and closure
• Timeline sidebar showing combined status history, workflow events, and correspondence

Fields:

• Message body (required)
• Internal note checkbox (staff-only visibility)

Closing Requests

URL: /research/request/:id/close/:type

Close a request when fulfilment is complete or the request is no longer needed.

Closure Reasons:

• Fulfilled
• Cancelled by researcher
• Duplicate
• Unable to fulfil
• Other

SLA Configuration

SLA policies are managed centrally. The default research request SLA is:

• Warning: 7 days (approaching deadline)
• Due: 10 working days
• Escalation: 14 days (breached — triggers escalation)

SLA computation starts when a request is triaged as "approved". The SLA status is visible on the requests dashboard and in individual request views.

"Request This Item" Button

On archival description (information object) pages, a "Request this item" button allows researchers to create a material request directly from the catalogue. The button:

• Submits via AJAX to /research/ajax/request-item
• Creates a new material request linked to the archival object
• Shows success/error feedback inline
• Only visible to logged-in, approved researchers

24. Material Retrieval & Custody

Overview

The custody system tracks the physical chain of custody for archival materials as they move between storage, staff, and researchers. Every handoff is recorded with timestamps, handlers, condition assessments, and optional barcode scans.

Custody Checkout

URL: /research/custody/:id/checkout

When materials are handed to a researcher:

Checkout Form Fields:

• Condition at handoff (Excellent, Good, Fair, Poor, Critical)
• Barcode scan (optional — for barcode-enabled collections)
• Destination (defaults to "Reading Room")
• Notes

What Happens:

1. A custody handoff record is created
2. A Spectrum movement record is auto-generated (movement reason: research_checkout)
3. The material request status changes to in_use
4. The physical object's access status updates to in_use
5. A workflow event is emitted for the audit trail
6. The item's current location updates to the reading room

Custody Check-In / Return

URL: /research/custody/:id/checkin

When materials are returned by a researcher:

Return Form Fields:

• Condition before (state when material was checked out)
• Condition after (state when returned)
• Notes (e.g., damage observations)

What Happens:

1. A custody handoff record is created (type: checkin)
2. A Spectrum movement record is auto-generated (movement reason: research_return)
3. The material request status changes to returned
4. The physical object's access status updates to available
5. Current location updates to "Return shelf (pending re-shelving)"

Return Verification

URL: /research/custody/:id/return-verify

An optional verification step after return, where a second staff member confirms:

• The material's condition matches what was reported
• The material is ready to be re-shelved
• Current location is updated to the original shelf location

Staff-to-Staff Transfer

Custody can be transferred between staff members (e.g., shift handover). A transfer records:

• From handler and to handler
• Condition at transfer
• Notes

Batch Checkout

URL: /research/custody/batch-checkout

Process multiple checkouts at once:

1. Select requests from the retrieval queue
2. Set a default condition and destination for all items
3. Review the list and uncheck any items to exclude
4. Submit — each item gets an individual custody record

Batch Return

URL: /research/custody/batch-return

Process multiple returns at once:

1. Select requests from the retrieval queue
2. For each item, set condition-before and condition-after individually
3. Add per-item notes if needed
4. Submit — each item gets an individual custody and movement record

Custody Chain

URL: /research/custody/chain/:object_id

View the full chain of custody for any archival object. The chain combines data from three sources:

Table Columns:

• Date, Source, Event Type, From (handler + location), To (handler + location), Condition, Confirmed (signature), Notes

Spectrum Movement Integration

Every custody handoff automatically creates a corresponding spectrum_movement record:

• Movement reference: RR-{request ID}
• Includes condition before/after
• Links back to the custody handoff via foreign key
• Compliant with Spectrum 5.1 Object Location and Movement Control procedures

25. Accessibility

WCAG 2.1 AA Compliance

All research and workflow screens comply with WCAG 2.1 Level AA accessibility standards.

Skip Navigation

Every page includes a "Skip to main content" link, visible when focused via keyboard (Tab key). This allows keyboard users and screen reader users to bypass the navigation and jump directly to the page content.

Screen Reader Support

ARIA Live Region — an invisible region (aria-live="polite") announces dynamic changes (AJAX updates, status changes) to screen readers without requiring a page reload.

Helper Functions (JavaScript):

• ahgAnnounce(message, priority) — announce a message to screen readers
• ahgFocusTo(selector) — programmatically move focus to an element

Data Tables

All data tables include:

• aria-label on the <table> element describing the table's purpose
• <caption class="visually-hidden"> with a detailed description
• scope="col" on all <th> header cells
• Row-level aria-label on checkboxes identifying the associated item

Status Badges

Status indicators never rely on colour alone:

• Every badge includes an icon and text alongside the colour
• Badges use role="status" and aria-label for screen reader context
• Priority badges: bolt icon (rush/red), arrow-up icon (high/yellow), dash icon (normal/grey)

Form Accessibility

• Required fields use aria-required="true"
• Validation errors use role="alert" and aria-invalid="true"
• Labels are programmatically associated with inputs via for/id or wrapping <label> elements

Keyboard Navigation

• All interactive elements (buttons, links, checkboxes, dropdowns) are reachable via Tab
• Escape key dismisses open modals
• Focus indicators use a visible 3px blue outline (:focus-visible)
• Batch select-all checkboxes toggle all items in the list

Decorative Icons

All decorative Font Awesome icons include aria-hidden="true" to prevent screen readers from announcing them. Icons that convey meaning include appropriate aria-label or accompanying visible text.

26. Rights & Access Policies (ODRL)

Overview

URL: /research/odrl/policies

ODRL (Open Digital Rights Language) policies define structured access rules for research materials. Policies are enforced at key access points throughout the Research Portal.

Creating Policies

Click Create Policy to open the policy form:

1. Target Type — select from: Archival Description, Collection, Project, Snapshot, Annotation, Assertion
2. Target — TomSelect autocomplete searches by name (not raw IDs)
3. Policy Type — Permission, Prohibition, or Obligation
4. Action Type — Use, Reproduce, Distribute, Modify, Archive, Display
5. Constraints (optional):
   • Restrict to Researchers — multi-select TomSelect to limit policy to specific researchers
   • Date From / Date To — temporal validity window
   • Max Uses — maximum number of permitted uses

Editing Policies

Click the pencil icon on any policy row to edit. All fields are pre-populated including researcher names (not IDs).

Policy Display

The policy list shows:

• Target with resolved name (e.g., "AI Test 4" instead of "#901233")
• Constraints displayed as readable text (researcher names, dates, max uses)

Enforcement

Policies are enforced at these access points:

Default behaviour: Resources with no policies are accessible (default-allow). Only explicit prohibitions block access. All decisions are logged to research_access_decision for audit.

Access Evaluation API

URL: /research/odrl/evaluate

Evaluate whether a specific action is permitted:

• Input: target type, target ID, researcher ID, requested action
• Output: permitted/prohibited with explanation and applicable policy

27. RO-Crate & DOI Minting

RO-Crate Packaging

URL: /research/ro-crate/:project_id

Package a research project as an RO-Crate (Research Object Crate):

• Follows the RO-Crate specification (FAIR data principles)
• Includes metadata, data files, and provenance information
• BagIt format for integrity verification
• Schema.org dataset description

Collection Packaging

URL: /research/ro-crate/collection/:id

Package a single collection as an RO-Crate.

JSON-LD Export

URL: /research/json-ld/:project_id

Export project metadata as JSON-LD for linked data applications.

DOI Minting

URL: /research/doi/:project_id

Mint a Digital Object Identifier for your research project:

• Integrates with DataCite API
• Generates DOI metadata from project information
• Registers the DOI with DataCite
• Tracks DOI status and updates

Reproducibility Pack

URL: /research/reproducibility/:project_id

Generate a complete reproducibility pack including:

• Project metadata
• Collection snapshots with hash verification
• Extraction job configuration and results
• Assertion graph
• Bibliography references
• DOI reference

28. Notifications

Viewing Notifications

URL: /research/notifications

Notifications are generated for:

• Project invitations
• Workspace invitations
• Peer review requests
• Booking confirmations
• Material request updates
• Search alert triggers
• Collaboration activity

Notification Preferences

Configure which notifications you receive:

• In-app notifications (always on)
• Email notifications (configurable per type)
• Digest frequency (immediate, daily, weekly)

API Access

URL: /research/notifications/api

JSON API for real-time notification polling:

• Get unread count
• Mark as read
• Mark all as read
• Delete old notifications

29. REST API & API Keys

API Key Management

URL: /research/profile/api-keys

Generate API keys for programmatic access:

1. Click Generate Key
2. Enter a descriptive name (e.g., "Python Script")
3. Select Permissions:
   • Read — access collections, annotations, bibliographies (checked by default)
   • Write — create/update collections, annotations
   • Search — query the catalogue (checked by default)
4. Set Expiration Date (leave blank for default 1 year)
5. Copy the generated key immediately — it is shown only once

Keys are stored in the central ahg_api_key table with scope enforcement. The key list shows: name, prefix, permissions, created date, last used, expiry, and status. Active keys can be revoked.

API Endpoints

Base URL: /api/research/

Authentication

Include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

Default rate limit: 1000 requests per day per key. Configurable per key.

30. ORCID Integration

Connecting ORCID

URL: /research/orcid/connect

1. Click "Connect ORCID"
2. You are redirected to ORCID.org
3. Authorize the application
4. You are redirected back with your ORCID iD linked

Benefits

• Verified researcher identity
• ORCID iD displayed on your profile
• Potential for automatic publication tracking
• Enhanced trust for institutional sharing

Disconnecting

URL: /research/orcid/disconnect

You can disconnect your ORCID iD at any time.

31. Institutional Sharing

Managing Institutions

URL: /research/admin/institutions (Admin only)

Register external institutions for collaboration:

• Name, Code, Description
• Contact name, email, phone
• Website, Country
• Agreement type and status

Sharing Projects

URL: /research/project/:id/share

Share a research project with an external institution:

1. Select an institution
2. Set access level (view, contribute, full)
3. Set expiry date
4. Generate access token

External Access

URL: /research/share/:token

External collaborators access shared projects via a unique token URL. They can view project resources according to their access level.

External Collaborators

Add external collaborators (non-researchers) to shares:

• Name, Email, Institution
• Access level and expiry
• Individual access tokens

32. Audit Trail

Audit Module

URL: /audit

The audit trail records all significant actions in the research portal:

Tracked Actions:

• Researcher registration, approval, rejection
• Booking creation, check-in, check-out
• Collection modifications
• Annotation creation and deletion
• Project changes
• Report generation
• API key creation and revocation

Viewing Audit Records

Exporting

URL: /audit/export

Export audit logs as CSV for compliance reporting.

What's Logged

Each audit entry contains:

• Action type (create, update, delete, approve, reject, etc.)
• Entity type and ID
• Old values (before change)
• New values (after change)
• Changed fields list
• User who performed the action
• Timestamp
• Module/plugin source

33. Administration

Researcher Management

URL: /research/researchers

Status pill tabs with live counts: All, Pending, Approved, Suspended, Expired.

Admin workflow:

1. Filter by status tab or search by name
2. Click a researcher to view details
3. Approve — sets status to "approved"
4. Suspend — blocks access until reinstated
5. View bookings, collections, and activity history

Researcher Type Management

URL: /research/admin/types

Configure researcher types with booking limits and permissions:

• Max advance booking days, max hours/day, max materials per booking
• Auto-approve, remote access, reproduction, export permissions
• Expiry period, priority level
• Delete button with protection — cannot delete types assigned to researchers

Reading Room Management

URL: /research/rooms

Configure reading rooms with the research sidebar:

• Name, Location, Description, Code
• Capacity, Opening/Closing time, Days open
• Active/Inactive status
• Seat management and equipment inventory links

Equipment Management

URL: /research/equipment?room_id=X

• Equipment inventory per room with type, brand, model, serial number, condition
• Equipment types from Dropdown Manager — admin-configurable (15 types: Microfilm Reader, Scanner, Computer, etc.)
• Manage in Dropdown Manager button for admins
• Maintenance logging with condition before/after, performer, next due date
• Maintenance history modal (AJAX-loaded) per equipment item

Statistics Dashboard

URL: /research/admin/statistics

• Summary cards: Researchers, Bookings, Reproductions, Citations (with sub-stats)
• Charts: Registrations over time (line), Bookings by room (bar)
• Tables: Projects & Collections, Bookings & Materials
• Breakdown cards: Researcher Types, Projects by Status, Reproductions by Status
• Most Active Items and Most Cited Items tables
• Most Active Researchers with booking and collection counts
• Date range filter with This Month / This Year shortcuts

Activity Log

URL: /research/activities

• Scheduled reading room activities (workshops, tours, orientations)
• Activity Log section showing all research actions from research_activity_log
• Filter by activity type with counts
• Shows: date, researcher name, type badge, entity, details

Compliance Dashboard

URL: /research/compliance/:project_id

Per-project compliance overview:

• Ethics milestone status (overall + individual milestones)
• ODRL policies applied to the project
• Security classification levels of linked resources
• Source trust scores with progress bars

Statistics Dashboard

URL: /research/admin/statistics

Administrative analytics:

• Active researchers count
• Bookings per day/week/month
• Most viewed items
• Most cited items
• Most collected items
• Active researchers ranking
• Usage trends over time

Ethics Milestones

URL: /research/ethics-milestones/:project_id

Track ethics approval milestones for projects:

• IRB/Ethics committee submission
• Approval status
• Conditions and modifications
• Renewal dates

34. Database Reference

Core Tables (64 tables)

Researcher Management:

• research_researcher — Researcher profiles
• research_researcher_audit — Archived/rejected researchers
• research_researcher_type — Configurable researcher types
• research_researcher_type_i18n — Type translations
• research_verification — ID/institutional verification
• research_password_reset — Password reset tokens

Reading Room:

• research_reading_room — Room definitions
• research_booking — Reading room bookings
• research_material_request — Material retrieval requests
• research_request_status_history — Request status tracking

Collections:

• research_collection — Researcher collections
• research_collection_item — Items in collections

Projects:

• research_project — Research projects
• research_project_collaborator — Project collaborators
• research_project_resource — Project resources
• research_project_milestone — Project milestones
• research_clipboard_project — Clipboard items

Workspaces:

• research_workspace — Collaborative workspaces
• research_workspace_member — Workspace members
• research_workspace_resource — Workspace resources
• research_discussion — Discussion threads

Annotations:

• research_annotation — Legacy annotations (v1)
• research_annotation_v2 — W3C Web Annotations (v2)
• research_annotation_target — Annotation targets/selectors

Knowledge Graph:

• research_assertion — Subject-predicate-object triples
• research_assertion_evidence — Evidence for assertions
• research_hypothesis — Research hypotheses
• research_hypothesis_evidence — Evidence for hypotheses
• research_source_assessment — Source quality assessment
• research_quality_metric — Automated quality metrics

Extraction:

• research_extraction_job — AI extraction jobs
• research_extraction_result — Extraction results
• research_validation_queue — Validation queue

Entity Resolution:

• research_entity_resolution — Entity matching proposals

Visualization:

• research_timeline_event — Timeline events
• research_map_point — Geographic map points

Bibliography:

• research_bibliography — Bibliography collections
• research_bibliography_entry — Bibliography entries

Search:

• research_saved_search — Saved searches with citation IDs
• research_search_alert_log — Alert event log

Reproductions:

• research_reproduction_request — Reproduction requests
• research_reproduction_item — Items in requests
• research_reproduction_file — Generated files

Reports:

• research_report — Research reports
• research_report_section — Report sections
• research_report_template — Report templates
• research_journal_entry — Journal entries

Collaboration:

• research_comment — Comments
• research_peer_review — Peer review records

Notifications:

• research_notification — User notifications
• research_notification_preference — Notification settings

Institutional:

• research_institution — External institutions
• research_institutional_share — Project shares
• research_external_collaborator — External collaborators

Rights:

• research_rights_policy — ODRL policies
• research_access_decision — Access decisions

API & Analytics:

• research_api_key — API keys
• research_api_log — API request log
• research_activity_log — Activity tracking
• research_citation_log — Citation usage log
• research_statistics_daily — Daily statistics
• research_document_template — Document templates
• research_snapshot — Immutable snapshots
• research_snapshot_item — Snapshot items
• research_request_correspondence — Staff/researcher correspondence threads on requests
• research_custody_handoff — Chain-of-custody handoff records (checkout, checkin, transfer, return, condition check)

35. Troubleshooting

Common Issues

Browser Compatibility

The Research Portal requires a modern browser:

• Chrome 90+
• Firefox 90+
• Safari 14+
• Edge 90+

JavaScript must be enabled. The portal uses Bootstrap 5, D3.js for visualizations, and Quill.js for rich text editing.

Getting Help

Contact your institution's archivist or system administrator for:

• Account activation issues
• Access permission changes
• Technical problems
• Feature requests

36. Studio — Grounded AI Artefact Generator

Available from v3.3.0. Path: project → Research Output → Studio (AI artefacts).

What it is

Studio turns the source items in your project's collections into a publishable artefact: a briefing, a study guide, a timeline, a Mermaid diagram, an audio script, even a downloadable spreadsheet. The model only "sees" the sources you select, and every factual claim it makes carries a [N] citation marker tied to the matching source in the sidebar.

How to generate an artefact

1. Open your project and click Studio (AI artefacts) in the Research Output card.
2. Pick an output type (8 available — see below).
3. Select one or more sources from the multi-select. The pool is drawn from any collection inside the current project, so add items to your collections first.
4. Click Generate. Generation typically takes 10–40 seconds; you'll be redirected to the artefact's view page when it finishes.

Output types

Reading the artefact page

The artefact page shows:

• The generated body on the left (rendered as plain text, Mermaid diagram, or .xlsx preview depending on type)
• A "Sources cited" sidebar listing every [N] marker that appears in the body, with title, reference code, snippet, and "Open source" link
• Generation metadata under the title — model name, token count, generation time

If the artefact is an .xlsx spreadsheet, a Download .xlsx button appears at the top. If it's audio and a TTS endpoint is configured, a Listen button appears.

What "grounded" means

Studio is configured to refuse invention. The model is instructed never to introduce facts, names, or dates that don't appear in the supplied sources, and to flag the absence of evidence explicitly. Use the popovers (next section) to verify each claim.

Errors

If the artefact lands in error status, an alert at the top of the page explains why (TTS endpoint not configured, LLM call failed, spreadsheet JSON malformed, etc.). The transcript or partial body is still kept on disk so the next attempt can re-use it.

37. Citation Hover Popovers

Available from v3.3.0. Active on Studio artefacts and any view that renders a <ul id="studio-citations"> block.

Every [N] marker on a citation-aware page becomes a hover popover when you point at it. The popover shows:

• The source title
• A 220-character snippet from the source's scope-and-content
• An "Open source" link

Clicking the marker scrolls the page to the matching source entry in the sidebar list and flashes it briefly so you can scan the full record.

The popovers work on keyboard focus too — tab to a marker and it pops up.

38. Researcher Notebooks

Available from v3.3.0. Path: sidebar → Notebooks.

What it is

A private scratchpad. Notebooks are owned by you, never shared, and exist outside the project structure. Use them for early-stage research before you commit to a project shape.

What goes in a notebook

Items can be pinned to the top of the notebook for quick access.

Creating a notebook

1. Click Notebooks in the sidebar.
2. Enter a title and optional summary on the left.
3. Click Create. You'll see it in the list on the right.

Adding items

Open a notebook and use the Add item card on the left. Choose a type, fill in title/body, optionally tick "Pin to top".

Promote to project

When a notebook outgrows its scratchpad status, click Promote to project at the top. The system will:

1. Create a new public research project with the notebook's title and summary
2. Add you as the owner-collaborator
3. Create a collection seeded with every source pin in the notebook
4. Mark the notebook as promoted (and lock the promote button)

Promote-to-project is idempotent — clicking twice returns the existing project.

39. Cross-Fonds Reasoning Queries

Available from v3.3.0. Path: sidebar → Cross-fonds query (or /research/cross-fonds-query).

When to use it

When the answer to your research question is spread across multiple fonds, and you want a single ranked list of hits instead of running the search separately on each fonds page.

How it works

1. Enter your query.
2. Multi-select the fonds / collections you want to search (the picker shows up to 200 top-level archival units).
3. Optionally tick Expand with thesaurus terms — if ahgSemanticSearchPlugin is enabled, the system will widen your query with related terms before fanning out.
4. Click Run.

The system fires one OpenSearch query per fonds scoped to that fonds's lft/rgt MPTT range, takes the top 10 hits from each, merges them by score, and returns the top 30. Each result row shows the title, reference code, snippet, score, and an "Open record" link.

What gets logged

Every cross-fonds query is persisted to research_cross_fonds_query with the query text, fonds list, result count, and elapsed milliseconds. This feeds the analytics dashboard's "Top search terms" tile.

40. Research Analytics Dashboard

Available from v3.3.0. Path: sidebar → Analytics (or /research/analytics).

Eight KPI tiles

Date range

Default is the last 30 days. Change the from/to dates at the top and click Apply.

Sections

• Daily volume bar chart — one bar per day
• Activity types — count of every distinct activity_type
• Top researchers — by event count
• Popular descriptions — most-viewed information objects
• Top search terms — most-searched query strings (extracted from activity log details)
• Popular collections
• Citations by style/format — Chicago/MLA/APA + RIS/BibTeX/etc.

The dashboard is read-only and aggregates already-logged data — running it does not affect activity logs.

41. Live Collaboration Panel

Available from v3.3.0. Path: project → Research Output → Live Collaboration (or /research/projects/:id/realtime/panel).

What you see

The panel polls every 3 seconds for two things:

• Online now — every collaborator currently looking at the project, each tagged with a distinct colour. Stale entries drop off after 90 seconds.
• Project comments — a threaded comment feed for the project. New comments appear without a page reload.

Posting a comment

Type into the box at the bottom and click the send icon. Comments are tied to the project (not to a specific record or item — for record-level annotations, use the W3C Annotation Studio).

Resolving a comment

Click Resolve under any comment. Resolved comments stay visible but are visually faded.

Shared annotations on IIIF canvases

Annotations you create with visibility = shared or public are visible to other project collaborators on the same canvas, without any extra setup. Other collaborators see the annotation on the W3C Annotation Studio page for that record.

42. Per-Record Citation Manager Export

Available from v3.3.0. Path: any record's Cite this record page (/research/cite/:slug).

In addition to the existing styled citation card (Chicago / MLA / APA / Harvard / UNISA / Turabian), you'll see a new Copy in citation manager format card with six download buttons:

Each download is a real file with the correct MIME type, so most reference managers will import it on first open. The filename is derived from the record's slug.

Every export is logged to the activity log (activity_type='cite_export', details.format) so admins can see which formats are popular.

43. ORCID Works Push & Pull

Available from v3.3.0. Path: sidebar → ORCID Works (or /research/orcid/works).

This is an extension of the existing ORCID OAuth flow (sidebar → ORCID).

Pull works

If your ORCID is linked, the page automatically pulls and displays your complete works list from your ORCID record: titles, types, years, journals, DOIs, put-codes.

Click Pull works to force a fresh fetch (the last-sync time is shown in the link card).

Unlink

Click Unlink to remove the saved tokens. Your works stay on ORCID; only the local link is cleared.

Tokens

Access and refresh tokens are stored AES-256-CBC encrypted using a key derived from the AtoM Heratio app secret. Tokens never appear in logs or the page itself.

What if ORCID isn't configured

If the operator hasn't set orcid_client_id / orcid_client_secret / orcid_redirect_uri, the page shows a clean "not configured" alert listing the exact ENV keys. No errors, no 500s.

44. Mobile Shell (PWA)

Available from v3.3.0. Path: phone browser → /research/mobile. Installable as a standalone app.

What it is

A phone-first researcher home. Designed for two scenarios:

1. Reading room — quickly check your reading list, log a journal entry, search for an item
2. Off-site — review collections, draft notes, queue annotations

Installing as an app

In Chrome / Safari on mobile, open /research/mobile, then tap the browser menu → Add to home screen. The portal will launch in standalone mode (no browser chrome).

Layout

• Top — your name, email, online/offline badge
• 4-button grid — Search, Notebooks, Bibliographies, Journal
• Quick journal entry — a one-tap journal-entry form
• Recent reading list — most-recent 50 items from your collections

Online / offline badge

The badge turns red when your phone reports offline. The badge updates without a page reload.

45. Offline Mode & Sync

Available from v3.3.0. Works hand-in-hand with the Mobile Shell (§44).

What's available offline

If you've visited the mobile shell at least once, the service worker has cached it. Going offline:

• The mobile home page still loads (from cache)
• The 4-button grid is still visible
• Other pages may not load until you're back online

Offline journal entries

When you submit a quick journal entry while offline, the form:

1. Stops the normal submit
2. Saves the entry to localStorage under the key heratio_offline_queue_v1
3. Shows a confirmation that the entry is queued

When your device reconnects, the queue is automatically POSTed to /research/sync/offline and applied as a real research_journal_entry row. The audit table research_offline_sync_log records the run.

What's supported in the queue

What's not supported

Comments on projects, ORCID actions, file uploads, and bookings cannot be queued offline; they require an online connection. If you try to submit one while offline you'll get a browser-level network error.

This manual covers ahgResearchPlugin v3.3.0. For the latest updates, check the plugin documentation in the AtoM Heratio repository.