Zotero Sync Extension for Directus

A Directus extension that automatically synchronizes bibliography records from Zotero API to populate citation data in your database.

Overview

This extension runs as a scheduled hook in Directus, fetching formatted citations from Zotero Group Library and updating the site_bib_cit table's full_record field with properly formatted HTML citations.

Features

• 🕒 Scheduled Execution: Runs daily at 3:00 AM
• 🔄 Automatic Sync: Processes records with Zotero keys but missing citations
• 📚 Zotero Integration: Fetches citations from Zotero Group API
• 🗃️ Database Updates: Updates full_record and last_synced fields
• 📊 Progress Tracking: Detailed logging of sync progress and errors
• ⚡ Batch Processing: Processes up to 50 records per run
• 🛡️ Error Handling: Graceful handling of API failures and network issues

Installation

Option 1: NPM Installation (Recommended)

npm install @lad-sapienza/directus-extension-zotero-sync

Option 2: Manual Installation

1. Place this extension in your Directus extensions/ directory:

   extensions/
   └── directus-extension-zotero-sync/
       ├── index.js
       ├── package.json
       └── README.md

2. Ensure your docker-compose.yml includes the extension environment variables:

   environment:
     - EXTENSIONS_AUTO_RELOAD=true
     - EXTENSIONS_CACHE_TTL=0
     - ZOTERO_GROUP_ID=336647  # Your Zotero Group ID

3. Mount the extensions directory:

   volumes:
     - ./extensions:/directus/extensions

Configuration

Environment Variables

• ZOTERO_GROUP_ID (required): Your Zotero group library ID

Database Requirements

The extension expects a table named site_bib_cit with the following fields:

• id (primary key)
• zotero (varchar): Zotero item key
• full_record (text): HTML formatted citation (updated by this extension)
• last_synced (timestamp): Last sync timestamp (updated by this extension)

How It Works

1. Schedule: Runs every night at 3:00 AM using cron pattern 0 3 * * *
2. Query: Finds records where zotero is not null but full_record is empty
3. Fetch: Retrieves formatted citations from Zotero API endpoint:

   https://api.zotero.org/groups/{GROUP_ID}/items/{ZOTERO_KEY}?format=json&include=citation

4. Update: Stores the HTML citation in full_record and sets last_synced timestamp
5. Logging: Provides detailed progress logs for monitoring

Sample Output

[zotero-sync] Starting daily Zotero sync job at 2025-10-11T21:03:00.000Z
[zotero-sync] Found 3 records needing sync
[zotero-sync] ✅ Updated record 1 with citation (42 chars)
[zotero-sync] ✅ Updated record 2 with citation (81 chars) 
[zotero-sync] Sync completed: 3/3 records updated

Citation Format

Citations are returned as HTML-formatted strings:

<span>Hammond, <i>Hammond 1967</i>.</span>
<span>Ceka, "Fortifikimi Antik i Butrinit Dhe i Territorit Të Presaibëve."</span>

Troubleshooting

Common Issues

1. Extension not loading: Check that package.json includes proper Directus metadata
2. Database connection errors: Verify the extension has access to database services
3. Zotero API failures: Check group ID and network connectivity
4. Schedule not running: Verify cron syntax and Directus version compatibility

Debug Mode

To test immediately instead of waiting for scheduled run, temporarily change the schedule:

// Change from daily at 3 AM
schedule('0 3 * * *', async () => {
// To every minute for testing  
schedule('* * * * *', async () => {

Remember to revert to the daily schedule after testing.

Performance

• Processing Rate: ~10-50 records per minute (limited by Zotero API)
• Batch Size: 50 records per run (configurable via .limit())
• Frequency: Once daily to respect API rate limits
• Memory Usage: Minimal - processes records sequentially

License

This extension is released with GNU AGPL v3 license.

Version History

• v1.0: Initial release with basic Zotero sync functionality
• v1.1: Added improved database connection handling and error recovery
• v1.2: Switched to daily scheduling and increased batch processing