Skip to content

Administrator Guide#

Overview#

The GitHub importer is implemented as a pluggable importer inside the invenio-importer module.

Each importer:

  • has a unique identifier
  • provides a frontend form
  • validates the submitted payload
  • creates or updates a draft

The GitHub importer is intended as a reference implementation for future importers.

Importer Architecture#

The GitHub importer consists of three layers:

  1. Frontend form
  2. Importer class
  3. Import service

Frontend#

The frontend form is responsible for:

  • collecting the GitHub release URL
  • calling the importer execution API
  • displaying validation errors

The GitHub importer form is registered in:

assets/js/invenio_importer/src/importerForms/registry.js

Example registration:

{
  github_release: GitHubReleaseForm
}

The form component is typically located in:

assets/js/invenio_importer/src/importerForms/GitHubReleaseForm.js

Importer Class#

The importer class is responsible for:

  • validating the payload
  • calling the import service
  • returning an ImportResult

Example structure:

class GitHubImporter(BaseImporter):
    id = "github-release"
    label = "GitHub Release"
    ui_component = "github_release"

    def run(self, identity, payload):
        ...

Typical responsibilities:

  • validate the url field
  • normalize the URL
  • call the GitHub import service
  • wrap errors as ImporterError

Import Service#

The import service contains the business logic.

Typical responsibilities:

  • retrieve the GitHub release metadata
  • map GitHub metadata into InvenioRDM metadata
  • create the draft using current_rdm_records_service.create()
  • return the created draft

The service is usually separate from the importer class so that:

  • it can be unit tested independently
  • logic can be reused
  • importers stay small and focused

Registering the Importer#

Importers are enabled through the IMPORTERS configuration variable.

Example:

IMPORTERS = [
    {
        "class": "invenio_importer.importers.github:GitHubImporter",
        "options": {},
    }
]

The importer will then automatically appear in:

  • the importer registry
  • the importer API
  • the frontend importer list

Importer Metadata#

Each importer should define the following fields:

id = "github-release"
label = "GitHub Release"
description = "Import a GitHub release into a draft"
icon = "github"
ui_component = "github_release"

Field Description#

Field Purpose
id Unique importer identifier used by the API
label Display name shown in the UI
description Description shown in the importer modal
icon Semantic UI icon name
ui_component Name of the frontend form component

API Endpoints#

The importer API exposes two endpoints.

List available importers#

GET /api/importer/importers

Example response:

{
  "hits": {
    "hits": [
      {
        "id": "github-release",
        "label": "GitHub Release",
        "description": "Import a GitHub release into a draft",
        "icon": "github",
        "ui": {
          "component": "github_release"
        }
      }
    ]
  }
}

Execute importer#

POST /api/importer/importers/github-release/execute

Example payload:

{
  "url": "https://github.com/owner/repository/releases/tag/v1.0.0"
}

Adding a New Importer#

To add a new importer:

  1. Create a new importer class that extends BaseImporter
  2. Create a corresponding frontend form
  3. Register the frontend form in registry.js
  4. Add the importer to the IMPORTERS configuration
  5. Implement the import service logic

Recommended structure:

invenio_importer/
├── importers/
│   ├── github.py
│   ├── template.py
│   └── ...
├── services/
│   ├── github.py
│   └── ...

Template Importer#

The module also includes a template importer used as a starting point for future implementations.

The template importer:

  • accepts a title
  • creates a minimal draft
  • returns the created draft

It is intended for:

  • development
  • testing
  • learning how to implement new importers

Example configuration:

IMPORTERS = [
    {
        "class": "invenio_importer.importers.template:TemplateImporter",
        "options": {},
    }
]

The GitHub importer should be tested at three levels:

  1. Importer validation tests
  2. Service tests
  3. API endpoint tests

Recommended tests:

  • missing URL returns validation error
  • invalid URL returns validation error
  • valid URL creates a draft
  • API list endpoint returns the importer
  • API execute endpoint returns a draft payload

  Last update : 13.04.2026

Last review : 13.04.2026