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.