OAI-PMH Setup & Troubleshooting for OJS: Complete Guide

OAI-PMH (Open Archives Initiative Protocol for Metadata Harvesting) enables your journal's metadata to be discovered and aggregated by search engines, repositories, and discovery services worldwide. Properly configured OAI-PMH is essential for visibility in Google Scholar, BASE, OpenAIRE, CORE, and institutional repositories. This guide covers OAI-PMH fundamentals, OJS configuration, and troubleshooting common issues.

Understanding OAI-PMH #

OAI-PMH is a protocol that allows metadata harvesters to retrieve structured information about your published articles. When services like Google Scholar, BASE, or CORE "harvest" your journal, they're using OAI-PMH to systematically collect metadata about your articles—titles, authors, abstracts, keywords, publication dates, and URLs.

How Harvesting Works #

1. Harvester requests: A service sends an OAI-PMH request to your journal's endpoint
2. OJS responds: Returns XML-formatted metadata for requested articles
3. Harvester processes: Service indexes metadata into their discovery system
4. Incremental updates: Subsequent requests fetch only new or modified records

Your OAI-PMH Endpoint #

Every OJS installation has an OAI-PMH endpoint at:

https://yourjournal.com/index.php/journalpath/oai

For multi-journal installations, each journal has its own endpoint. The site-wide endpoint aggregates all journals:

https://yourjournal.com/index/oai

Testing Your OAI-PMH Endpoint #

Before registering with harvesters, verify your endpoint works correctly:

Basic Identity Check #

Add ?verb=Identify to your OAI-PMH URL:

https://yourjournal.com/index.php/journalpath/oai?verb=Identify

This should return XML containing your journal's name, base URL, admin email, and earliest datestamp.

List Available Metadata Formats #

https://yourjournal.com/index.php/journalpath/oai?verb=ListMetadataFormats

OJS supports multiple formats:

• oai_dc - Dublin Core (basic, widely supported)
• nlm - NLM JATS (rich scholarly metadata)
• marc - MARC format (library systems)
• marcxml - MARC in XML

List Records #

https://yourjournal.com/index.php/journalpath/oai?verb=ListRecords&metadataPrefix=oai_dc

This retrieves actual metadata records. If no records appear but your journal has published content, there's a configuration problem.

OJS OAI-PMH Configuration #

Enable OAI-PMH #

In OJS 3.x, OAI-PMH is enabled by default. Verify in config.inc.php:

[oai]
; Enable OAI
oai = On

; OAI Repository identifier
repository_id = ojs.yourjournal.com

Configure Journal Metadata #

Complete metadata improves harvesting quality. In Settings → Journal → Masthead:

• Journal title (accurate and consistent)
• ISSN (both print and online if applicable)
• Publisher name
• Journal description/about text

Article Metadata Requirements #

Each article should have complete metadata:

• Title (in publication language)
• Authors with affiliations
• Abstract
• Keywords
• Publication date
• DOI (if registered)
• PDF galley assigned

Troubleshooting OAI-PMH Issues #

Problem: No Records Returned #

Symptoms: ListRecords returns empty or "noRecordsMatch" error.

Causes & Solutions:

• No published articles: OAI-PMH only exposes published content in published issues
• Missing galleys: Articles need galleys assigned to appear
• Unpublished issues: Verify issues are marked as published (not just scheduled)
• Database issues: Rebuild the article search index in Administration

Problem: 404 or Error on OAI Endpoint #

Symptoms: OAI URL returns 404 Not Found or server error.

Causes & Solutions:

• Wrong URL path: Verify journal path matches exactly (case-sensitive)
• mod_rewrite issues: Check .htaccess is properly configured for OJS
• OAI disabled: Verify oai = On in config.inc.php
• Plugin conflicts: Disable recently added plugins to test

Problem: Harvesters Report Errors #

Symptoms: Google Scholar or other services report harvesting failures.

Causes & Solutions:

• Timeout issues: Large journals may timeout; ensure adequate PHP timeout settings
• Memory limits: Increase PHP memory_limit if harvesting fails mid-process
• Invalid XML: Special characters in metadata may break XML; clean problematic records
• SSL issues: Ensure valid SSL certificate; some harvesters reject invalid SSL

Problem: Incomplete Metadata #

Symptoms: Records appear but missing titles, authors, or abstracts.

Causes & Solutions:

• Metadata not entered: Review article submission metadata in OJS
• Encoding issues: Non-UTF8 characters may be stripped
• Language settings: Metadata in non-default language may not export

OAI-PMH Sets #

OAI-PMH "sets" allow harvesters to request specific subsets of your content:

?verb=ListRecords&metadataPrefix=oai_dc&set=journal:journalpath

OJS automatically creates sets for:

• Each journal in multi-journal installations
• Each section within journals (if configured)

View available sets:

?verb=ListSets

Registering with Harvesters #

Google Scholar #

Google Scholar automatically discovers OJS journals but you can expedite indexing:

1. Submit your OAI-PMH URL via Google Search Console
2. Ensure metatags plugin is enabled in OJS
3. Verify PDF galleys are accessible

BASE (Bielefeld Academic Search Engine) #

1. Visit the BASE content provider suggestion form
2. Submit your OAI-PMH endpoint URL
3. BASE validates and begins harvesting if accepted

OpenAIRE #

1. Register at OpenAIRE's repository registration
2. Provide OAI-PMH endpoint and journal details
3. May require OpenAIRE-compliant metadata (install OpenAIRE plugin)

CORE #

1. Register as a data provider at CORE
2. Submit OAI-PMH endpoint
3. CORE harvests full-text when accessible

Enhancing OAI-PMH Output #

Install Additional Metadata Plugins #

OJS plugins can enhance OAI-PMH output:

• Dublin Core Plugin: Standard OJS plugin for basic metadata
• OpenAIRE Plugin: Adds OpenAIRE-compliant metadata format
• JATS Plugin: Provides JATS XML metadata export
• Google Scholar Plugin: Enhances metatags for Google Scholar

Resumption Tokens #

For large journals, OAI-PMH uses resumption tokens to paginate results. If harvesters report incomplete harvesting:

• Ensure PHP sessions work correctly
• Check session save path is writable
• Verify no firewall blocks long-running connections

Monitoring Harvesting #

Periodically verify your content is being harvested:

• Google Scholar: Search site:yourjournal.com in Google Scholar
• BASE: Search your journal name in BASE and verify article count
• OAI-PMH logs: Some harvesting services provide dashboard statistics

If article counts seem low, review OAI-PMH configuration and re-test the endpoint.