External Services Integration

DOCiD™ integrates with multiple external services to provide comprehensive scholarly communication and research infrastructure capabilities. Each service is abstracted through dedicated service classes that provide consistent interfaces, authentication management, and error handling.

Core Integration Features:

• Authentication Token Management: Automatic token refresh and error handling
• Batch Processing: Background jobs for bulk operations
• Error Handling: Comprehensive logging and fallback mechanisms
• Data Transformation: Service-specific metadata formatting
• Rate Limiting: Respect external service API limits
• Caching: Store external service responses when appropriate

CORDRA (Corporation for Digital Repository Advancement) provides distributed digital object repository services with Handle generation and management capabilities.

Key Features:

• Handle Generation: Automatic Handle identifier assignment
• Metadata Storage: JSON-based object metadata
• Digital Object Repository: Distributed object storage
• Version Management: Object versioning and lifecycle management

# Push recent publications to CORDRA
python push_recent_to_cordra.py

# Update and push all publications
python update_and_push_to_cordra.py

# Individual publication push
python push_to_cordra.py --publication-id 123

Crossref is the official DOI registration agency for scholarly content. DOCiD™ integrates with Crossref for DOI metadata registration and management.

Integration Capabilities:

• DOI Registration: Automated DOI assignment and registration
• Metadata Deposit: Structured metadata submission
• Citation Linking: CrossRef participation for citation networks
• ORCID Integration: Author identification through ORCID
• Fundref Support: Funder identification and acknowledgment

# Environment variables
CROSSREF_API_URL=https://api.crossref.org
CROSSREF_API_KEY=your_crossref_api_key
CROSSREF_DEPOSITOR_EMAIL=depositor@institution.edu
CROSSREF_REGISTRANT=Institution Name

# API endpoints
POST /api/v1/crossref/register-doi
GET /api/v1/crossref/doi-status/{doi}
PUT /api/v1/crossref/update-metadata/{doi}

DataCite provides DOI registration services specifically designed for research data, software, and other non-traditional research outputs. DOCiD™ can integrate with DataCite as an alternative to Crossref for DOI minting.

DataCite vs Crossref in DOCiD:

• DataCite Focus: Research data, datasets, software, models
• Crossref Focus: Traditional publications, journal articles
• DOCiD Strategy: Use DataCite for data-centric outputs
• Prefix Management: Separate DOI prefixes for different content types

# DataCite DOI storage in database
publication_files.external_identifier = "10.82433/dataset.001"
publication_files.external_identifier_type = "datacite_doi"

# DataCite metadata mapping
{
  "doi": "10.82433/DOCID.2024.001",
  "creators": [{
    "name": publication_creators.family_name + ", " + given_name,
    "nameIdentifiers": [{
      "nameIdentifier": publication_creators.identifier,
      "nameIdentifierScheme": "ORCID"
    }]
  }],
  "titles": [{
    "title": publications.document_title
  }],
  "publisher": "African PID Alliance",
  "publicationYear": 2024,
  "types": {
    "resourceTypeGeneral": "Dataset",
    "resourceType": resource_types.resource_type
  },
  "schemaVersion": "http://datacite.org/schema/kernel-4"
}

DataCite-Specific Features in DOCiD:

African Research Data Examples:

POST /api/v1/datacite/register-doi
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
    "data": {
        "type": "dois",
        "attributes": {
            "doi": "10.82433/docid.2024.climate.001",
            "creators": [
                {
                    "name": "Okonkwo, Amara",
                    "nameType": "Personal",
                    "givenName": "Amara",
                    "familyName": "Okonkwo",
                    "nameIdentifiers": [
                        {
                            "nameIdentifier": "https://orcid.org/0000-0002-1234-5678",
                            "nameIdentifierScheme": "ORCID"
                        }
                    ],
                    "affiliation": [
                        {
                            "name": "University of Cape Town",
                            "affiliationIdentifier": "https://ror.org/01ggx4157",
                            "affiliationIdentifierScheme": "ROR"
                        }
                    ]
                }
            ],
            "titles": [
                {
                    "title": "Climate Change Impact Data for Southern Africa 2024",
                    "titleType": "MainTitle"
                },
                {
                    "title": "Impacto na Mudança Climática em África Austral 2024",
                    "titleType": "TranslatedTitle",
                    "lang": "pt"
                }
            ],
            "publisher": "African Climate Research Initiative",
            "publicationYear": 2024,
            "resourceType": {
                "resourceTypeGeneral": "Dataset",
                "resourceType": "Climate Data"
            },
            "subjects": [
                {
                    "subject": "Climate Change",
                    "subjectScheme": "LCSH"
                },
                {
                    "subject": "Southern Africa",
                    "subjectScheme": "Geographic"
                }
            ],
            "fundingReferences": [
                {
                    "funderName": "National Research Foundation",
                    "funderIdentifier": {
                        "funderIdentifier": "https://doi.org/10.13039/501100001321",
                        "funderIdentifierType": "Crossref Funder ID"
                    },
                    "awardNumber": "NRF-2024-CCA-001"
                }
            ]
        }
    }
}

DOI State Management:

• Draft: DOI reserved but not yet publicly resolvable
• Registered: DOI publicly resolvable with metadata
• Findable: DOI with URL that resolves to a landing page
• Deleted: DOI marked as no longer active

CSTR provides persistent identifier services for scientific and technological resources in China, supporting international research collaboration.

CSTR Services:

• CSTR Identifier Assignment: Format: CSTR:xxxxx.xx.xxxx-xxxx
• Resource Registration: Scientific dataset and publication registration
• Metadata Standards: Chinese metadata schema compliance
• Cross-Border Collaboration: International research project support

# Setup CSTR service
./setup_cstr_service.sh

# Test single CSTR registration
python test_single_cstr.py

# Update all CSTR identifiers
python update_all_cstr_identifiers.py

# CSTR identifier format
CSTR:16389.09.A08V-0001

ROR provides persistent identifiers for research organizations worldwide, enabling accurate institutional attribution and affiliation tracking.

ROR Integration Features:

• Organization Lookup: Real-time ROR ID verification
• Institutional Metadata: Complete organization information retrieval
• African Institutions: Comprehensive coverage of African research institutions
• API Integration: RESTful API for organization data

GET /api/v1/ror/search?query=university%20cape%20town

Response:
{
    "status": "success",
    "data": {
        "ror_id": "https://ror.org/01ggx4157",
        "name": "University of Cape Town",
        "country": "South Africa",
        "types": ["Education"],
        "aliases": ["UCT"],
        "external_ids": {
            "GRID": {"all": "grid.7836.a"},
            "ISNI": {"all": ["0000 0004 1937 1151"]}
        }
    }
}

ORCID provides persistent digital identifiers for researchers, enabling accurate author identification and attribution across publications.

ORCID Features:

• Author Identification: Unique researcher identifiers
• Profile Integration: Researcher profile and affiliation data
• Publication Attribution: Accurate authorship linking
• OAuth Integration: Secure authentication for researchers
• African Researchers: Growing coverage of African researcher community

# Creator with ORCID
{
    "given_name": "Thabo",
    "family_name": "Mthembu",
    "orcid": "https://orcid.org/0000-0002-1825-0097",
    "affiliation": "University of Cape Town",
    "ror_id": "https://ror.org/01ggx4157",
    "role": "Author"
}

# ORCID API validation
GET https://pub.orcid.org/v3.0/0000-0002-1825-0097/record

The APA Handle ID is DOCiD's primary persistent identifier service, provided through the African PID Alliance. It implements the Handle System protocol with a dedicated African prefix.

Key Features:

• Prefix: 20.500.14351 - Dedicated African namespace
• Format: 20.500.14351/[unique-suffix]
• Resolution: Global Handle resolution via hdl.handle.net
• Persistence: Guaranteed long-term accessibility
• Local Control: African-managed identifier infrastructure

# Generated DOCiD Handle
20.500.14351/b23a80ce9b1a6ef21588
20.500.14351/41e8074ca70348616b78
20.500.14351/b1f26969fdec417b55c6

# Resolution URL
https://hdl.handle.net/20.500.14351/b23a80ce9b1a6ef21588

# Database field mapping
publication_documents.generated_identifier
publication_files.generated_identifier

ARK identifiers provide decentralized, persistent identification for digital objects, particularly suitable for cultural heritage and archival materials.

ARK Structure:

• Format: ark:/[NAAN]/[Name][Qualifier]
• NAAN: Name Assigning Authority Number
• Flexibility: Supports versioning and variants
• Metadata: Built-in metadata support via "?" and "??" inflections

# ARK identifier example
ark:/12345/x6np1wh8

# With qualifier for versions
ark:/12345/x6np1wh8/v1.2

# Metadata access
ark:/12345/x6np1wh8?     # Returns brief metadata
ark:/12345/x6np1wh8??    # Returns policy metadata

Integration with arXiv for preprint identification, particularly for physics, mathematics, computer science, and related disciplines.

arXiv ID Format:

• New Format: arXiv:YYMM.nnnnn (post-2007)
• Old Format: arXiv:subject-class/YYMMnnn (pre-2007)
• Versioning: vN suffix for versions (e.g., 2301.12345v2)
• Resolution: Direct access via arxiv.org

# Modern arXiv IDs
arXiv:2301.12345
arXiv:2301.12345v2  # Version 2

# Resolution URLs
https://arxiv.org/abs/2301.12345
https://arxiv.org/pdf/2301.12345.pdf

Generic Handle System implementation for persistent identification, providing the underlying infrastructure for DOI and other Handle-based systems.

Handle System Features:

• Format: [prefix]/[suffix]
• Resolution: Global Handle resolution infrastructure
• Flexibility: Multiple resolution targets
• Metadata: Structured Handle records
• Integration: CORDRA repository support

# Handle formats in DOCiD
publication_files.handle_identifier
publication_documents.handle_identifier

# Resolution via Handle proxy
https://hdl.handle.net/[prefix]/[suffix]

# Direct Handle resolution
https://doi.org/[prefix]/[suffix]  # For DOI handles

Decentralized persistent identifiers using distributed ledger technology for tamper-proof, permanent identification without central authority dependency.

dPID Characteristics:

• Technology: Blockchain-based persistence
• Decentralization: No single point of failure
• Immutability: Cryptographically secured records
• Verification: Public verifiability of identifiers
• Independence: Organization-independent persistence

# dPID structure (conceptual)
dpid:chain:contract:identifier

# Example implementation
dpid:eth:0x1234...abcd:pub-2024-001

# Verification via smart contract
contract.verifyIdentifier(dpid)

ISNI provides unique identifiers for public identities of parties involved in creative activities, including researchers, authors, and institutions.

ISNI Features:

• Format: 16-digit number (0000 0000 0000 000X)
• Coverage: Individuals and organizations
• Interoperability: Links with ORCID, VIAF, and other systems
• Authority Control: Disambiguates name variants
• Global Reach: International ISO standard

# ISNI format
0000 0001 2150 919X  # Individual researcher
0000 0004 0620 0244  # Research institution

# URL resolution
https://isni.org/isni/0000000121509195

# Database storage
publication_organizations.identifier = "0000000460200244"
publication_organizations.identifier_type = "isni"

Ringgold provides unique identifiers for institutions and organizations in the scholarly research supply chain, with comprehensive hierarchical organization data.

Ringgold Features:

• Format: Numeric identifier (e.g., 12345)
• Hierarchy: Parent-child institutional relationships
• Metadata: Rich organizational metadata
• Coverage: Global institutional database
• Updates: Continuously maintained and verified

# Ringgold ID examples
6740   # Harvard University
62468  # University of Cape Town
311766 # African Academy of Sciences

# Hierarchical structure
{
  "ringgold_id": "62468",
  "name": "University of Cape Town",
  "parent_id": "62467",  # Parent institution
  "country": "South Africa",
  "type": "University"
}

External services require proper configuration through environment variables:

# CSTR Configuration
CSTR_CLIENT_ID=your_cstr_client_id
CSTR_SECRET=your_cstr_secret
CSTR_API_URL=https://cstr.cn/api

# Crossref Configuration  
CROSSREF_API_URL=https://api.crossref.org
CROSSREF_API_KEY=your_crossref_api_key
CROSSREF_DEPOSITOR_EMAIL=depositor@institution.edu

# Local Contexts Configuration
LC_API_KEY=your_local_contexts_api_key
LC_BASE_URL=https://localcontexts.org/api

# ROR Configuration (Public API)
ROR_API_URL=https://api.ror.org

# ORCID Configuration
ORCID_CLIENT_ID=your_orcid_client_id
ORCID_CLIENT_SECRET=your_orcid_client_secret
ORCID_API_URL=https://api.sandbox.orcid.org