elAPI Plugins

Data import and export tools for eLabFTW electronic lab notebooks

Releases · elAPI Framework · eLabFTW

---

About

elAPI Plugins is a desktop application for bulk importing and exporting resources and experiments in eLabFTW instances. It provides a browser-based GUI for researchers and lab managers who need to migrate, back up, or batch-update electronic lab notebook entries from CSV and Excel files.

The project is developed as part of the INF Project of CRC 1638 at the Heidelberg University Biochemistry Center (BZH) and is built on top of the elAPI framework.

---

Features

Export

• Export resources (by category) or experiments to .xlsx files
• Automatically extracts and flattens extra fields from eLabFTW metadata
• Strips HTML from body content for clean spreadsheet output

Import

• Create new resources or experiments from CSV files
• Update existing entries by providing entity IDs in the CSV
• Supported fields per entry:
  • Title, body, date, category, template
  • Tags (via the eLabFTW /tags sub-endpoint)
  • File attachments (single files or directories)
  • Extra fields (matched to existing template fields with type coercion)
  • Entity links (experiment-to-experiment, experiment-to-resource)
• Intelligent column matching: handles non-breaking spaces, tabs, and case variations
• Automatic delimiter detection for CSV files (comma, semicolon, tab, pipe)

CSV Templates

• Download a pre-filled CSV template for any resource category or experiment template
• Templates include all standard columns plus the extra fields defined in the eLabFTW template, ready to fill in and re-import

Automatic Updates

• The application checks for new releases on GitHub at startup and displays a notification banner when an update is available

---

Prerequisites

elAPI must be installed and configured with a valid eLabFTW API key before using these tools.

pip install elapi
elapi init

Follow the elAPI installation guide for detailed instructions on setting up API credentials.

---

Installation

macOS

1. Download the latest .dmg from the Releases page:
   • Apple Silicon (M1 / M2 / M3 / M4): elAPI_Plugins_arm64.dmg
   • Intel: elAPI_Plugins_x86_64.dmg
2. Open the .dmg and drag elAPI Plugins into your Applications folder.
3. Launch the application from Launchpad or Finder.

Note: On first launch, macOS may block the application because it is not distributed through the App Store. To resolve this, go to System Settings > Privacy & Security, scroll to the Security section, and click Open Anyway. Then relaunch the application.

Windows

1. Download the latest .exe installer from the Releases page.
2. Run the installer and follow the on-screen instructions.
3. Launch elAPI Plugins from the Start Menu or desktop shortcut.

Linux

Linux users can run the application from source. Python 3.11 or later is required.

git clone https://github.com/dantypas3/elAPI_Plugins.git
cd elAPI_Plugins
./scripts/setup_env.sh
source .build/bin/activate
python gui/gui.py

.build is the canonical project virtual environment for local development and notebooks. Packaging uses a separate temporary environment so it does not overwrite your working interpreter.

Development / notebooks

Create or refresh the shared project environment with:

./scripts/setup_env.sh
source .build/bin/activate

If you want Jupyter to use the same interpreter, register .build as the kernel:

.build/bin/python -m ipykernel install --user --name elapi-plugins --display-name "elAPI Plugins"

---

Usage

After launching, the GUI opens automatically in your default browser at http://127.0.0.1:1991.

Action	Description
Export resources	Select a category and download all matching resources as an .xlsx file.
Export experiments	Download all experiments as an .xlsx file.
Download resource template	Select a resource category and download a blank CSV with all standard and extra-field columns for that category.
Download experiment template	Select an experiment template and download a blank CSV with all standard and extra-field columns for that template.
Import from CSV	Upload a CSV file to create new entries or update existing ones. Select the target type, assign a category or template, and optionally enable update mode.

CSV format

The importer automatically detects delimiters and encoding. Column names are matched flexibly (case-insensitive, whitespace-tolerant). Recognized columns include:

Column	Purpose
title	Entry title
body	Main text / body content
tags	Comma-, semicolon-, or pipe-separated tags
category / category id	Numeric category ID
template	Numeric template ID (used on creation)
date	Entry date (various formats supported)
experiment id / resource id	Existing entry ID (for update mode)
attachments / files_path	Path to a file or directory to attach
experiments links	Comma-separated experiment IDs to link
resources links	Comma-separated resource IDs to link

Any additional columns are matched against the extra fields defined in the entry's template and updated accordingly.

Update markers

When CSV import is used in update mode, you can place special marker values in individual cells:

Marker	Effect
$delete_V	Replaces that cell value with an empty value before the row is processed.
$delete_F	Removes that column from the current row before the row is processed.

These markers must match exactly. For example, delete_V or $delete_v are treated as normal text.

---

Project Structure

src/
  factories/          Factory classes for instantiating importers and exporters
  services/
    importers/        CSV-to-eLabFTW import logic (resources, experiments)
    exporters/        eLabFTW-to-Excel export logic
  updater/            GitHub release checker and asset downloader
  utils/              Shared utilities (CSV parsing, endpoints, logging)
gui/                  Flask-based web GUI
config/               Runtime configuration files
tests/                Test suite

---

License

Copyright (c) 2025 Biochemistry Center(BZH), CRC 1638, Heidelberg University.

This project is licensed under the GNU Affero General Public License v3.0 or later.

---

_{Heidelberg University · Biochemistry Center (BZH) · SFB 1638 · INF Project}