Heratio Help Center article. Category: Plugin Reference.

ahgDoiPlugin - Technical Documentation

Version: 1.0.0
Category: Identifiers / Integration
Dependencies: atom-framework, DataCite API account

Overview

DOI (Digital Object Identifier) minting and management via DataCite for persistent identifiers on archival records. Supports batch minting, metadata synchronization, queue-based processing, and lifecycle management.

Features

Database Schema

ERD Diagram

+-----------------------------------------------+
|                  ahg_doi                       |
+-----------------------------------------------+
| PK id BIGINT UNSIGNED                         |
| FK object_id INT                              |---+
|    object_type VARCHAR(50)                    |   |
|                                               |   |
| -- DOI DATA --                                |   |
|    doi VARCHAR(255) UNIQUE                    |   |
|    datacite_id VARCHAR(255)                   |   |
|    status ENUM                                |   |
|    prefix VARCHAR(50)                         |   |
|    suffix VARCHAR(100)                        |   |
|                                               |   |
| -- METADATA --                                |   |
|    object_title VARCHAR(500)                  |   |
|    target_url TEXT                            |   |
|    metadata_json JSON                         |   |
|                                               |   |
| -- STATUS --                                  |   |
|    minted_at TIMESTAMP                        |   |
|    synced_at TIMESTAMP                        |   |
|    verified_at TIMESTAMP                      |   |
|    deactivated_at TIMESTAMP                   |   |
|    deactivation_reason TEXT                   |   |
|                                               |   |
| -- AUDIT --                                   |   |
| FK created_by INT                             |   |
| FK repository_id INT                          |   |
|    created_at TIMESTAMP                       |   |
|    updated_at TIMESTAMP                       |   |
+-----------------------------------------------+   |
                    |                               |
                    | 1:N                           |
                    v                               |
+-----------------------------------------------+   |
|              ahg_doi_queue                     |   |
+-----------------------------------------------+   |
| PK id BIGINT UNSIGNED                         |   |
| FK object_id INT                              |---+
|    action ENUM                                |
|    status ENUM                                |
|    priority INT                               |
|    attempts INT                               |
|    max_attempts INT                           |
|    error_message TEXT                         |
|    scheduled_at TIMESTAMP                     |
|    started_at TIMESTAMP                       |
|    completed_at TIMESTAMP                     |
|    created_at TIMESTAMP                       |
|    updated_at TIMESTAMP                       |
+-----------------------------------------------+

+-----------------------------------------------+
|              ahg_doi_config                    |
+-----------------------------------------------+
| PK id BIGINT UNSIGNED                         |
| FK repository_id INT                          |
|    datacite_repository_id VARCHAR(255)        |
|    datacite_password VARCHAR(255) ENCRYPTED   |
|    datacite_prefix VARCHAR(50)                |
|    datacite_shoulder VARCHAR(50)              |
|    environment ENUM('test', 'production')     |
|    auto_mint TINYINT                          |
|    default_state ENUM                         |
|    url_template TEXT                          |
|    is_active TINYINT                          |
|    created_at TIMESTAMP                       |
|    updated_at TIMESTAMP                       |
+-----------------------------------------------+

+-----------------------------------------------+
|              ahg_doi_log                       |
+-----------------------------------------------+
| PK id BIGINT UNSIGNED                         |
| FK doi_id BIGINT UNSIGNED                     |
|    action VARCHAR(50)                         |
|    status VARCHAR(50)                         |
|    request_data JSON                          |
|    response_data JSON                         |
|    error_message TEXT                         |
| FK performed_by INT                           |
|    created_at TIMESTAMP                       |
+-----------------------------------------------+

DOI States

Service Methods

DoiService

namespace ahgDoiPlugin\Services;

class DoiService
{
    // Configuration
    public function getConfig(?int $repositoryId = null): ?object
    public function saveConfig(array $data): bool
    public function testConnection(?int $repositoryId = null): array

    // Minting
    public function mintDoi(int $objectId): array
    public function queueForMinting(int $objectId, string $action = 'mint'): int
    public function processQueue(int $limit = 50): array
    public function buildMetadata(object $object): array
    
    // Sync
    public function syncDoi(int $doiId): array
    public function bulkSync(array $options = []): array
    public function queueForSync(array $options = []): int
    
    // State Management
    public function updateDoiState(int $doiId, string $state): array
    public function deactivateDoi(int $doiId, string $reason = ''): array
    public function reactivateDoi(int $doiId): array
    
    // Queries
    public function getDoi(int $id): ?object
    public function getDoiByObjectId(int $objectId): ?object
    public function hasDoi(int $objectId): bool
    public function getStats(): array
    public function getRecentDois(int $limit = 10): Collection
    
    // Export
    public function exportToCsv(array $options = []): string
    public function exportToJson(array $options = []): string
    
    // Verification
    public function verifyResolution(int $doiId): array
}

DataCite API Integration

Endpoints Used

Authentication

// Base64 encoded credentials
$auth = base64_encode("{$repositoryId}:{$password}");
$headers = [
    'Authorization' => "Basic {$auth}",
    'Content-Type' => 'application/vnd.api+json',
];

API Environments

Metadata Mapping

DataCite Schema 4.4 Mapping

Resource Type Mapping

CLI Tasks

doi:mint

php symfony doi:mint [options]

Options:
  --id=ID              Mint for specific record
  --all                Mint for all eligible records
  --repository=ID      Filter by repository
  --level=LEVEL        Filter by level of description
  --limit=N            Maximum to process (default: 100)
  --dry-run            Preview without minting

doi:sync

php symfony doi:sync [options]

Options:
  --all                Sync all DOIs
  --id=ID              Sync specific DOI
  --status=STATUS      Filter by status
  --repository=ID      Filter by repository
  --limit=N            Maximum to sync
  --queue              Queue for async processing
  --dry-run            Preview without syncing

doi:deactivate

php symfony doi:deactivate [options]

Options:
  --id=ID              DOI record ID to deactivate
  --object-id=ID       Object ID whose DOI to deactivate
  --reason=TEXT        Reason for deactivation
  --reactivate         Reactivate instead of deactivate
  --list-deleted       List all deactivated DOIs
  --dry-run            Preview without changes

Auto-Mint Hook

// In ahgDoiPluginConfiguration.class.php
$this->dispatcher->connect('QubitInformationObject.postSave', [$this, 'onRecordSave']);

public function onRecordSave(sfEvent $event)
{
    $record = $event->getSubject();
    
    if ($service->shouldAutoMint($record)) {
        $service->queueForMinting($record->id, 'mint');
    }
}

Auto-Mint Conditions

1. Record is published (publication_status_id = published)
2. Auto-mint enabled for repository
3. Record level matches configured levels
4. No existing DOI for record

Queue Processing

Queue Worker

// Process pending queue items
$service->processQueue(50);

// Cron job (every 5 minutes)
*/5 * * * * cd /path/to/atom && php symfony doi:process-queue >> /var/log/atom/doi.log 2>&1

Queue Actions

Routes

GlamIdentifierService Integration

// In GlamIdentifierService.php
public function getMintedDoi(int $objectId): ?string
{
    $doi = DB::table('ahg_doi')
        ->where('object_id', $objectId)
        ->whereIn('status', ['findable', 'registered'])
        ->first();
    
    return $doi->doi ?? null;
}

public function hasMintedDoi(int $objectId): bool
{
    return DB::table('ahg_doi')
        ->where('object_id', $objectId)
        ->whereIn('status', ['findable', 'registered', 'draft'])
        ->exists();
}

public function getAllIdentifiers(int $objectId, ?string $sector = null): array
{
    $identifiers = [];
    
    // Add DOI if exists
    if ($doi = $this->getMintedDoi($objectId)) {
        $identifiers['doi'] = [
            'type' => 'doi',
            'value' => $doi,
            'url' => "https://doi.org/{$doi}",
            'display' => "DOI: {$doi}",
        ];
    }
    
    // Add sector-specific identifiers...
    return $identifiers;
}

Record Badge Integration

The _recordBadge.php partial is included in information object views:

// In sfIsadPlugin/templates/indexSuccess.php
<?php include_partial('doi/recordBadge', ['resource' => $resource]) ?>

Features:

• Shows DOI link if exists
• "Mint DOI" button for admins if no DOI
• AJAX minting without page reload
• Status badge (findable, registered, draft)

AHG Settings Integration

System Info Page

DOI statistics displayed via getDoiStatistics():

• Total DOIs
• Count by status
• Queue pending
• Configuration status

Cron Jobs Page

DOI commands listed:

• doi:mint - Batch minting
• doi:sync - Metadata sync
• doi:deactivate - Deactivation
• doi:process-queue - Queue processing

Error Handling

Retry Logic

$maxAttempts = 3;
$retryDelay = [60, 300, 900]; // 1min, 5min, 15min

if ($attempts < $maxAttempts) {
    $queue->update([
        'status' => 'pending',
        'scheduled_at' => now()->addSeconds($retryDelay[$attempts]),
        'attempts' => $attempts + 1,
    ]);
}

Security

• DataCite passwords stored encrypted
• Admin-only access to minting
• Audit log for all DOI operations
• Rate limiting on API endpoints

Part of the Heratio AHG Framework