esn-cy/esn-activities-api

v1.0.0 2026-08-02 11:52 UTC

Requires

• esn-cy/omnia: ^v1.3
• symfony/property-access: ^8.1
• symfony/property-info: ^8.1

Requires (Dev)

• drupal/core: ^10

Apache-2.0

• Andreas Michael

Published on Packagist.org on 2026-08-02 11:54 UTC

README

ESN Activities API

A Drupal module that connects with the Erasmus Generation API to fetch activity data and automatically synchronize it into Drupal content entities.

Features

• Custom Entities: Defines Enum-backed custom content entities for Activity, Cause, and SDG.
• Background Synchronization: Utilizes Drupal's Queue API and Queue Workers to process API pagination in the background without causing PHP timeouts.
• Dual-Sync Modes:
  • Fast Sync: Runs frequently to fetch recently modified or created activities.
  • Full Sync: Runs periodically to guarantee historical consistency.
• Smart Data Mapping: Intelligently maps deeply nested DTOs (Data Transfer Objects) to Drupal fields, including physical locations, external links, timestamps, and taxonomy references.
• Self-Healing: Automatically handles API downtime by leveraging Queue exceptions to requeue failed pages.

Dependencies

This module relies on the following custom ESN modules:

• esn_accounts_api (Provides the Organisation entity)
• omnia (Provides OmniaSettings)

(Ensure your project's composer.json includes the packages.esn.org repository to resolve these dependencies).

Installation

1. Require the module via Composer or place it in your modules/custom directory.
2. Enable the module via the Drupal UI or using Drush:

   drush en esn_activities_api

3. Drupal will automatically install the necessary database tables for the Activity, Cause, and SDG entities.

Configuration

Navigate to Omnia > ESN Activities API Settings (/admin/config/system/esn-activities-api) to configure the module:

• Enable Sync: Toggle the synchronization engine on or off.
• Global Mode: Determines whether to sync all activities globally or filter them by your National Organization's Country Code (set up in Omnia Settings).
• API Key: The authentication key for the Erasmus Generation API.
• Sync Intervals: Configure how often the Fast Sync and Full Sync cutoff timestamps are calculated.
• Manual Triggers: Use the manual trigger buttons to instantly push a Fast or Full sync job to the queue.

Architecture

The synchronization process is entirely decoupled and automated:

1. CronService: Hooked into Drupal's cron. It evaluates your configured intervals, calculates the correct timestamp cutoffs, and pushes an initial payload to the esn_activities_api_sync queue.
2. SyncWorker (QueueWorker): Processes the queue item in the background.
   • It calls the EndpointService to fetch a specific page from the remote API.
   • It passes the deserialized ActivityDTO objects to the ActivityImporterService.
   • If the API returns more items, the worker creates a new queue item for page + 1 to process the next batch.
3. ActivityImporterService: Checks if the remote activity was modified since the last sync. If so, it maps all data, handles relational Cause and SDG creations, and persists the Drupal entities.