Export Destinations#

NexusLIMS uses a plugin-based export framework to publish experimental records to multiple repository systems. After building XML records from microscopy data, the system can export them to one or more configured destinations.

Overview#

The export framework supports:

  • Multiple destinations running in parallel or sequence

  • Configurable strategies for handling export failures

  • Inter-destination dependencies (e.g., cross-linking between systems)

  • Per-destination tracking in the database

  • Automatic retry for transient failures

Records are exported immediately after successful building, with results logged to the UploadLog table for tracking and debugging.

Available Export Destinations#

CDCS (Primary)#

Added in version 1.0.0.

The Configurable Data Curation System (CDCS) is the primary and default export destination for NexusLIMS. CDCS provides:

  • Web-based record viewing and search

  • Schema validation and versioning

  • Access control and permissions

  • RESTful API for programmatic access

  • Public/private workspace management

Configuration: See CDCS Integration for required settings:

  • NX_CDCS_URL - CDCS instance URL

  • NX_CDCS_TOKEN - API authentication token

CDCS exports have priority 100 (highest) and run first to ensure records are available for cross-linking by other destinations.

What gets exported:

  • Complete XML record

  • XML file uploaded to CDCS document storage

  • Record indexed and searchable via CDCS interface

  • Unique record ID assigned for cross-referencing

Frontend repository: NexusLIMS-CDCS

eLabFTW#

Added in version 2.4.0.

eLabFTW is an open-source electronic lab notebook system. NexusLIMS supports creating eLabFTW experiment records that correspond to individual microscopy sessions with:

  • HTML-formatted session summary

  • Structured metadata using eLabFTW’s extra_fields schema

  • Automatic tagging (instrument, user, NexusLIMS)

  • Full XML record attached as file

  • Cross-link to CDCS record (if CDCS export enabled)

Configuration: See eLabFTW Integration for settings:

  • NX_ELABFTW_URL - eLabFTW instance URL

  • NX_ELABFTW_API_KEY - API authentication key

  • NX_ELABFTW_EXPERIMENT_CATEGORY - Optional category assignment

  • NX_ELABFTW_EXPERIMENT_STATUS - Optional status assignment

eLabFTW exports have priority 85 and run after CDCS to enable cross-linking.

What gets exported:

  • Experiment title: “NexusLIMS Experiment - {session_id}”

  • Body: HTML with session details and CDCS link

  • Tags: NexusLIMS, instrument name, username

  • Metadata: Structured extra_fields (session times, instrument, user, CDCS URL)

  • Attachment: Complete XML record file

Example experiment view:

<h1>NexusLIMS Microscopy Session</h1>

<h2>Session Details</h2>
<ul>
  <li><strong>Session ID</strong>: 2025-01-27_10-30-15_abc123</li>
  <li><strong>Instrument</strong>: FEI-Titan-TEM-012345</li>
  <li><strong>User</strong>: jsmith</li>
  <li><strong>Start</strong>: 2025-01-27T10:30:15+00:00</li>
  <li><strong>End</strong>: 2025-01-27T14:45:00+00:00</li>
</ul>

<h2>Related Records</h2>
<ul>
  <li><a href="https://cdcs.example.com/data/123">View in CDCS</a></li>
</ul>

LabArchives#

Added in version 2.6.0.

LabArchives is a commercial electronic lab notebook system. NexusLIMS supports exporting session records to LabArchives with:

  • HTML-formatted session summary with a gallery of preview images

  • A list of all data files contained in the experiment

  • The full XML record attached as a file

  • Cross-link to CDCS record (if CDCS export enabled)

Configuration: See LabArchives Integration for settings:

  • NX_LABARCHIVES_URL - LabArchives instance URL

  • NX_LABARCHIVES_ACCESS_KEY_ID - API access key ID

  • NX_LABARCHIVES_ACCESS_PASSWORD - API signing password

  • NX_LABARCHIVES_USER_ID - Pre-authenticated user ID (uid)

  • NX_LABARCHIVES_NOTEBOOK_ID - Optional target notebook (uses Inbox if unset)

LabArchives exports have priority 90 and run after CDCS (to allow cross-linking).

What gets exported:

  • Notebook structure: NexusLIMS Records/{instrument_pid}/{YYYY-MM-DD — session_id} page (auto-created if it doesn’t exist)

  • HTML summary: Session details and optional link to CDCS record

  • Attachment: Complete XML record file

Export Workflow#

The export process runs automatically as part of process_new_records() workflow:

  1. Build record: The experimental record is generated from session data and validated against the NexusLIMS experiment schema

  2. Export to destinations: export_records() determines which exporters should be run, depending on system configuration

  3. Execute by priority: Individual destination export routines are run in priority order (highest first)

  4. Track results: Export outcomes are logged to the UploadLog table

  5. Update session status:

    • COMPLETED if exports succeed

    • BUILT_NOT_EXPORTED if exporting fails

  6. Archive successfully exported files: Move to uploaded/ directory

Export Strategies#

Multi-destination behavior can be configured with the NX_EXPORT_STRATEGY setting, depending on your deployment’s needs:

Strategy

Behavior

all (default)

Export to all enabled destinations. Fails if any destination fails.

first_success

Stop after first successful export. Remaining destinations skipped.

best_effort

Attempt all destinations. Succeeds if at least one succeeds.

Example configuration:

NX_EXPORT_STRATEGY=best_effort  # Continue even if some destinations fail

Inter-Destination Dependencies#

Export destinations can access results from higher-priority destinations to create cross-links:

# In eLabFTW export destination
def export(self, context: ExportContext) -> ExportResult:
    # Get CDCS result (priority 100, runs first)
    cdcs_result = context.get_result("cdcs")
    
    if cdcs_result and cdcs_result.success:
        # Include CDCS URL in eLabFTW metadata
        cdcs_url = cdcs_result.record_url
        # Add to experiment body and metadata...

This enables:

  • Cross-linking: eLabFTW experiments link to CDCS records

  • Cascading updates: Downstream destinations use upstream IDs

  • Conditional behavior: Skip exports if upstream dependencies fail

See Inter-Destination Dependencies in the developer guide for implementation details.

Monitoring Exports#

Database Tracking#

All export attempts are logged to the upload_log table:

SELECT destination_name, success, timestamp, error_message
FROM upload_log
WHERE session_identifier = 'your-session-id'
ORDER BY timestamp DESC;

Schema: UploadLog

Session Status#

Session records track overall export status in session_log.record_status:

Status

Meaning

TO_BE_BUILT

Session needs record generation

COMPLETED

Record built and exported successfully

BUILT_NOT_EXPORTED

Record built but all exports failed

ERROR

Record building failed

NO_FILES_FOUND

No files found for session

Check session status:

SELECT instrument, record_status, timestamp
FROM session_log
WHERE session_identifier = 'your-session-id';

Export Logs#

Detailed export logs are written to NX_LOG_PATH (or NX_DATA_PATH/logs/):

  • nexuslims_record_builder.log - Main processing log with export results

  • Individual destination errors logged with context

Troubleshooting#

Export Failures#

Common issues:

Problem

Solution

CDCS authentication failed

Verify NX_CDCS_TOKEN is valid and user has write permissions

eLabFTW API errors

Check NX_ELABFTW_API_KEY and network connectivity

All exports failed

Check logs in NX_LOG_PATH for detailed error messages

Session marked BUILT_NOT_EXPORTED

Review upload_log table for per-destination failures

Debug export issues:

  1. Check configuration:

    from nexusLIMS.config import settings
print(f"CDCS URL: {settings.NX_CDCS_URL}")
print(f"eLabFTW URL: {settings.NX_ELABFTW_URL}")

  2. Query upload logs:

    SELECT * FROM upload_log 
WHERE success = 0 
ORDER BY timestamp DESC 
LIMIT 10;

  3. Review main log file for detailed errors

Validation#

Test export destination configuration:

from nexusLIMS.exporters.registry import get_enabled_destinations

for dest in get_enabled_destinations():
    is_valid, error = dest.validate_config()
    print(f"{dest.name}: {'✓' if is_valid else '✗'} {error or ''}")

Developing Custom Destinations#

NexusLIMS’s plugin architecture makes it easy to add new export destinations. No core modifications needed—just drop a Python file in nexusLIMS/exporters/destinations/.

Common use cases:

  • Export to institutional repositories (Zenodo, Figshare, Dataverse)

  • Push to cloud storage (S3, Azure, Google Cloud)

  • Integrate with other LIMS systems

  • Custom archival workflows

See Writing Export Destination Plugins for:

  • Complete implementation guide

  • Protocol requirements and testing strategies

  • Example implementations

  • Inter-destination dependency patterns

Quick start: Copy an existing destination (e.g., elabftw.py) and customize for your target system.

API Reference#

Key modules for export functionality:

Summary#

The export framework provides:

  • Multiple repository support (CDCS, eLabFTW, LabArchives, custom destinations)

  • Automatic export after record building

  • Configurable failure handling strategies

  • Inter-destination cross-linking

  • Complete tracking and logging

  • Plugin-based extensibility

Export destinations are configured via environment variables and automatically activated when credentials are provided. No additional setup required beyond configuration.