Skip to main content
Version: ILLiad 9.2 (Current)

DOI Resolver

The ILLiad DOI Resolver is a free web page feature that enhances the Article Request form by allowing patrons to look up articles by DOI or PubMed ID and automatically populate citation fields. When configured with an open access service, it can also detect freely available versions and offer patrons a direct download link — reducing unnecessary ILL transactions.

Download​

Two packages are available depending on how much functionality you want to enable:

PackageDescriptionDownload
DOI Resolver OnlyCitation lookup and form pre-fill. No open access checking.ILLiad_DOI_Resolver.zip
DOI Resolver + Open AccessCitation lookup plus open access discovery via Unpaywall or LibKey.ILLiad_DOI_and_Open_Access.zip

You can start with DOI Resolver Only and upgrade to the Open Access version later by replacing DOIResolver.js.

Package Contents​

Both packages contain the same set of files:

FileDescription
DOIResolver.jsCore JavaScript file. Configure your service credentials at the top of this file, then deploy to your js\ folder.
include_doi_resolver.htmlHTML partial that renders the DOI/PMID lookup widget on the request form. Place in your default ILLiad web folder.
ArticleRequest.htmlSample request page showing how to include the script and widget. Optional — use as a replacement or as a reference for manual edits.
README.mdFull installation reference covering prerequisites, file locations, configuration options, API details, and troubleshooting.
MIGRATION_GUIDE.mdStep-by-step walkthrough for migrating from the retired OpenAccessButton addon.

Installation​

Step 1: Download​

Download the appropriate zip package and extract it. Review README.md for full details. Note the path to your ILLiad web root folder.

Step 2: Place Files​

  • Copy DOIResolver.js into the js\ subfolder of your default ILLiad web folder.
  • Copy include_doi_resolver.html into your default ILLiad web folder (same level as ArticleRequest.html).

Step 3: Configure DOIResolver.js​

Open DOIResolver.js in a text editor and update the CONFIGURATION section at the top of the file. If you are using the DOI Resolver Only package, you can leave the service configuration blank. If using DOI Resolver + Open Access, configure exactly one open access service — either Unpaywall or LibKey.

Refer to the README.md included in the package for detailed configuration instructions and options. If you are migrating from the retired OpenAccessButton addon, see MIGRATION_GUIDE.md for a step-by-step walkthrough.

Step 4: Edit Your Web Page​

Choose one of two approaches:

Option A: Replace ArticleRequest.html​

Use this if you have not customized your ArticleRequest.html page.

  1. Copy ArticleRequest.html from the zip package.
  2. Paste it into your default ILLiad web folder.
  3. Overwrite the existing file when prompted.
  4. Also copy include_doi_resolver.html to the same folder.
  5. Verify DOIResolver.js is already in the js\ subfolder.
  6. Test your ArticleRequest page in a browser.

Option B: Manually Edit Your Customized Page​

Use this if you have a customized ArticleRequest.html you want to preserve. You will need to add a script tag in the <head> section and an include statement inside the <fieldset> of your page. Also copy include_doi_resolver.html into your default ILLiad web folder.

Refer to the README.md and MIGRATION_GUIDE.md included in the package for detailed instructions on where to place the script tag and include statement.

What Patrons See​

Once installed, a DOI and PubMed ID lookup widget appears at the top of the Article Request form. Patrons enter a DOI or PubMed ID and click Look Up. The resolver returns one of the following results:

Citation Found — No Open Access​

The citation metadata (author, title, journal, volume, issue, pages, DOI) is retrieved and displayed for patron review. The patron confirms the citation, and the ILL request form is auto-populated with the data. Even without an open access hit, the citation pre-fill saves patrons time and reduces typos.

Open Access Available​

The resolver finds citation metadata and also detects that a free version of the article is available. A blue Open Access Available box appears with a View Open Access Version link. The patron can download the article immediately without submitting an ILL request. If the patron still needs ILL, they can confirm the citation and submit the pre-filled form.

Retracted Article Warning​

When using LibKey, the resolver can detect retracted articles. If an article has been retracted, a red warning box replaces the normal open access prompt. The warning includes a link to the retraction notice so patrons can review it. The patron can still choose to fill the ILL form — the decision is theirs. This is a key integrity feature that prevents patrons from unknowingly citing retracted research.

note

Retraction detection is available with the LibKey service. Unpaywall does not provide retraction data.

Error Retrieving ID​

If the DOI or PubMed ID cannot be found, an error message appears in red directly below the Look Up button. The form below the widget remains fully accessible — patrons can continue filling it in manually. Two error types exist: one for DOIs and one for PubMed IDs, with messages specific to what was entered.

Troubleshooting​

Configuration Issues​

  • "Configuration validation failed": Ensure SERVICE_TYPE is exactly "unpaywall" or "libkey" (case-sensitive). Verify all required credentials are filled in for your selected service.
  • LibKey authentication errors (401/403): Verify your API key and Library ID are correct with no extra spaces. Contact Third Iron support at support@thirdiron.com to confirm your credentials are active.
  • Open access links not appearing: The article may not be available as open access. Check the browser console (F12) for API errors. Test with a known open access DOI such as 10.1371/journal.pone.0123456.

Common Issues​

  • Cached old version: Clear browser cache or hard refresh (Ctrl+F5 on Windows, Cmd+Shift+R on Mac). Increment the version number in the script tag query string.
  • PubMed API rate limiting: PubMed limits to 3 requests per second without an API key. A retry button appears automatically. Wait 2–3 seconds between lookups.
  • Form not autofilling: Check the browser console for errors. Verify the DOI format is correct. Check the Network tab in browser developer tools to see if API calls are being made.

Browser Console Debugging​

The script logs diagnostic information to the browser console. To check:

  1. Open browser developer tools (F12).
  2. Go to the Console tab.
  3. Look for messages starting with DOIResolver: for configuration and API status.
  4. Check the Network tab to verify API calls are completing successfully.

API Dependencies​

The DOI Resolver relies on the following external APIs. All are free except LibKey.

APIEndpointRate LimitCost
DOI.orghttps://doi.org/{doi}NoneFree
PubMedhttps://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi3/secFree
Unpaywallhttps://api.unpaywall.org/v2/{doi}ReasonableFree
LibKeyhttps://api.thirdiron.com/public/v1/libraries/{id}/articles/doi/{doi}CommercialPaid

Installation Checklist​

Verify all of the following before going live:

  • README reviewed
  • DOIResolver.js placed in the js\ subfolder
  • include_doi_resolver.html placed in the default ILLiad web folder
  • API credentials configured in DOIResolver.js (Open Access package only)
  • SERVICE_TYPE set to "unpaywall" or "libkey" (Open Access package only)
  • ArticleRequest.html updated (Option A or Option B)
  • Script tag with cache-busting parameter confirmed in <head>
  • Tested in browser — DOI lookup widget appears and populates citation fields

Support​