Federation Module User Guide¶

Overview¶

The Federation Module enables AtoM Heratio instances to share data across multiple institutions. It provides three core capabilities:

OAI-PMH Harvesting - Import records from other repositories using the OAI-PMH protocol
Federated Search - Search across multiple institutions simultaneously
Vocabulary Synchronization - Share and synchronize taxonomies between peers

Getting Started¶

Accessing Federation Settings¶

Log in as an administrator
Navigate to Admin > Federation or go to /index.php/federation

Understanding Peers¶

A "peer" is another AtoM/Heritage Platform instance that you want to connect with. Each peer has: - A name (human-readable identifier) - A base URL (the OAI-PMH endpoint) - Optional API key for authentication - Configuration for harvesting, search, and vocabulary sync

Managing Federation Peers¶

Adding a New Peer¶

Go to Admin > Federation > Peers
Click Add Peer
Fill in the required fields:
Name: A descriptive name (e.g., "National Archives")
Base URL: The peer's OAI-PMH URL (e.g., https://archives.example.org/oai)
API Key: If the peer requires authentication
Configure harvesting options:
Metadata Prefix: Usually oai_dc or oai_heritage
Default Set: Leave empty to harvest all, or specify a set
Harvest Interval: How often to auto-harvest (in hours)
Click Save

Editing a Peer¶

Go to Admin > Federation > Peers
Click the peer name or the edit icon
Modify settings as needed
Click Save

Deactivating a Peer¶

Go to Admin > Federation > Peers
Click the peer name
Uncheck Active
Click Save

Deactivated peers are not included in harvesting, search, or sync operations.

OAI-PMH Harvesting¶

Manual Harvest¶

Go to Admin > Federation > Peers
Click Harvest next to the peer
Optionally set:
From Date: Only harvest records modified after this date
Until Date: Only harvest records modified before this date
Set: Specific set to harvest
Click Start Harvest

Viewing Harvest History¶

Go to Admin > Federation > Harvest Log
Filter by peer, date, or status
Click a session to see details:
Records created, updated, deleted
Errors encountered
Duration

Harvest Status Values¶

Status	Description
Running	Harvest is in progress
Completed	Harvest finished successfully
Failed	Harvest encountered an error
Cancelled	Harvest was manually stopped

Federated Search¶

Federated search allows users to search across all connected peers simultaneously.

Enabling Federated Search¶

Go to Admin > Federation > Peers
Click a peer name
Go to the Search tab
Check Enable Federated Search
Configure:
Search API URL: Usually auto-detected
Timeout: How long to wait for response (ms)
Max Results: Maximum results from this peer
Priority: Lower numbers appear first
Click Save

Using Federated Search¶

Go to the main search page
Check Include federated results or use the federated search URL
Enter your search terms
Results from all peers are merged and displayed with source attribution

Search Result Sources¶

Each result shows: - The peer it came from (with link) - The original URL at the source repository - A relevance score

Vocabulary Synchronization¶

Vocabulary sync keeps taxonomies consistent across institutions.

Configuring Vocabulary Sync¶

Go to Admin > Federation > Vocabulary Sync
Click Configure Sync
Select:
Peer: The peer to sync with
Taxonomy: Which taxonomy to synchronize
Direction: Pull, Push, or Bidirectional
Conflict Resolution: How to handle conflicts

Sync Direction Options¶

Direction	Description
Pull	Import terms from the remote peer
Push	Export terms to the remote peer
Bidirectional	Both import and export terms

Conflict Resolution Options¶

Option	Description
Prefer Local	Keep local terms when conflicts occur
Prefer Remote	Use remote terms when conflicts occur
Skip	Don't sync conflicting terms
Merge	Combine translations from both

Running a Sync¶

Go to Admin > Federation > Vocabulary Sync
Click Sync Now next to the configuration
Review the results:
Terms added
Terms updated
Conflicts encountered

Viewing Sync History¶

Go to Admin > Federation > Vocab Sync Log
Filter by peer, taxonomy, or status
Click a session for details

Federation status values are managed through the AHG Dropdown system for easy customization.

Go to Admin > AHG Dropdown or /index.php/ahgDropdown
Filter by "federation" to see all federation-related dropdowns

Federation Taxonomies¶

Taxonomy	Purpose
`federation_sync_direction`	Pull, Push, Bidirectional options
`federation_conflict_resolution`	Conflict handling strategies
`federation_harvest_action`	Created, Updated, Deleted
`federation_session_status`	Running, Completed, Failed, Cancelled
`federation_mapping_status`	Term mapping states
`federation_change_type`	Vocabulary change types
`federation_search_status`	Search result states

Adding Custom Values¶

Go to Admin > AHG Dropdown
Select the federation taxonomy
Click Add Term
Enter code, label, and optional color
Click Save

Troubleshooting¶

Harvest Fails Immediately¶

Check the peer URL is accessible
Verify the API key if authentication is required
Check the peer's OAI-PMH endpoint is responding

Search Returns No Results from a Peer¶

Verify federated search is enabled for the peer
Check the search timeout isn't too low
Verify the peer's search API is accessible

Vocabulary Sync Shows Conflicts¶

Review the conflict resolution setting
Consider using "Merge" for translations
Check for duplicate terms with different cases

Slow Federated Search¶

Increase timeout for slow peers
Reduce max results per peer
Lower priority for less important peers

Best Practices¶

Start with Pull: When first connecting, use "Pull" direction to import existing terms
Use Sets: Configure OAI sets to harvest only relevant content
Regular Harvests: Set appropriate harvest intervals (24h is common)
Monitor Logs: Regularly check harvest and sync logs for errors
Test Connectivity: Before enabling features, test that peers are accessible