Heratio Help Center article. Category: User Guide.

Heratio - ORCID Integration: User Manual

Version: 1.0.0 Date: May 2026 Author: The Archive and Heritage Group (Pty) Ltd

Table of Contents

1. Introduction
2. What ORCID Gives You
3. Fetch from ORCID (registration)
4. Fetch from ORCID (profile)
5. Connect & Sync (full OAuth)
6. The ORCID page
7. Scheduled sync
8. Public vs Member API
9. Configuration
10. Privacy
11. Troubleshooting

1. Introduction

ORCID (Open Researcher and Contributor ID) is a free, persistent digital identifier that distinguishes a researcher from every other researcher with the same or a similar name. An ORCID iD looks like 0000-0002-1670-2416.

Heratio integrates with ORCID so that researchers can:

• Auto-populate their researcher profile from their public ORCID record (no retyping)
• Link their ORCID iD to their Heratio researcher account
• Pull their publication list ("Works") from ORCID into the archive
• Push citations from the archive back to their ORCID Works

There are two levels of integration, and you can use either or both:

2. What ORCID Gives You

Linking saves time and improves data quality:

• Name disambiguation - your authorship is recognised correctly even if another researcher shares your name.
• One-click profile - first name, last name, institution, department, position and research interests come straight from ORCID.
• Publication sync - your Works list is pulled in, so reproduction requests and bibliographies cite you correctly.
• Citation push - items you work with in the archive can be added to your ORCID record.

3. Fetch from ORCID (registration)

When you register as a researcher (/research/publicRegister or the staff register form):

1. Type your ORCID iD into the ORCID iD field (format 0000-0000-0000-0000).
2. Click Fetch from ORCID.
3. Heratio reads your public ORCID record and fills in the empty fields: first name, last name, institution, department, position, research interests, and email where public.
4. Review the filled values, complete anything still blank, and submit.

The Fetch button only fills empty fields - it never overwrites something you have already typed. If a field differs, it tells you which ones it left alone so you can clear and re-fetch to overwrite.

4. Fetch from ORCID (profile)

The same Fetch from ORCID button is on your researcher profile page (/research/profile), beside the ORCID iD field. Use it any time to refresh your profile fields from your public ORCID record.

5. Connect & Sync (full OAuth)

The Connect & Sync with ORCID button (on the profile page and the ORCID page) performs the full three-legged OAuth handshake:

1. You are redirected to orcid.org.
2. You sign in at ORCID with your ORCID iD and password (Heratio never sees your password).
3. You authorise Heratio to read your record and update your Works.
4. ORCID redirects you back; Heratio stores an encrypted access token.

Once connected, Heratio can pull your Works list and push citations. This is the level you need for publication sync, not just profile auto-fill.

6. The ORCID page

/research/orcid is your ORCID control panel:

• Linked state - shows your ORCID iD, scope, token expiry, last works-sync time, last profile-sync time, and works count.
• Pull profile from ORCID - refresh your profile fields from the public record (works even without a full OAuth link, using the iD on file).
• Pull Works from ORCID - import your publications list (requires Connect & Sync first, for the token).
• Unlink - remove the ORCID link.

If you have not linked yet but your profile already has an ORCID iD on file, the page offers a Pull profile from ORCID button directly.

7. Scheduled sync

An Artisan command keeps linked researchers in sync automatically:

php artisan ahg:orcid-sync          # all linked researchers
php artisan ahg:orcid-sync --researcher=25
php artisan ahg:orcid-sync --force  # ignore the 24h freshness window

It runs daily at 01:30 via the Laravel scheduler. It short-circuits cleanly when ORCID is not configured.

8. Public vs Member API

ORCID offers two API tiers; Heratio supports both via the ORCID_API_BASE setting:

The free Public API is enough for Fetch-from-ORCID and profile pull. Pushing citations to a researcher's Works needs the Member API plus the researcher's OAuth authorisation.

9. Configuration

Fetch from ORCID + Pull profile need no configuration at all - they read the public ORCID record tokenless against pub.orcid.org, so a researcher can auto-populate immediately with zero ORCID setup.

Connect & Sync is self-service per researcher - there is no global admin / .env step. On your /research/orcid page, the "My ORCID app credentials" panel lets you register your own free ORCID client and paste its Client ID + Secret:

1. Go to https://orcid.org/developer-tools and sign in.
2. Register for the free public API; set the redirect URI to exactly the value shown on the page (https://your-host/research/orcid/callback).
3. Paste the Client ID and Client Secret into the form and Save. Pick Public API (free) or Member API (to push citations).
4. Click Connect & Sync - your OAuth now uses your client.

Credentials are stored per researcher (researcher_orcid_credential, secret encrypted at rest). An administrator never has to manage ORCID for individual researchers.

Optional global fallback (.env)

An operator may still set a single institutional client in .env as a fallback for researchers who haven't entered their own. This is optional:

A researcher's own credentials always take precedence over the global fallback.

10. Privacy

• Heratio reads only the public portion of an ORCID record unless the researcher authorises more via Connect & Sync.
• The researcher's ORCID password is entered only at orcid.org during OAuth; Heratio never receives or stores it.
• Access tokens are stored encrypted at rest (researcher_orcid_link.access_token_encrypted).
• A researcher can unlink at any time, which deletes the stored token.

11. Troubleshooting

For technical operators, see docs/reference/orcid-integration-implementation.md.