Import-Integration

• Was ist die Flyo Import Integration?
• Allgemeine Anforderungen an die Quelle
  • Anforderungen an die Struktur
  • Anforderungen an den Identifier
  • Pagination
• Anforderungen an JSON-Quellen
• Beispiel: Google Spreadsheet als CSV-Quelle verwenden
  • Tabelle vorbereiten
  • Tabelle veröffentlichen
• Transformationen und Feldanforderungen
  • Text und Textarea
  • Datumsfelder
  • Datetime-Felder
  • Bild- und Dateifelder
  • Allgemeine Empfehlungen für saubere Importe

Was ist die Flyo Import Integration?

Die Flyo Import Integration dient dazu, Inhalte automatisiert aus externen Quellen in das Flyo System zu importieren. Typische Quellen sind JSON-APIs oder veröffentlichte CSV-Dateien.

Der wichtigste Zweck dieser Integration ist nicht nur der einmalige Import, sondern die laufende Synchronisation. Wenn sich die Quelldaten ändern, kann Flyo bestehende Inhalte wiedererkennen, Änderungen übernehmen und je nach Konfiguration auch Vorschläge für Aktualisierungen erzeugen.

Damit das zuverlässig funktioniert, muss jeder Datensatz aus der Quelle eindeutig identifizierbar sein. Flyo verwendet dafür einen stabilen Quell-Identifier, der im Mapping auf source_id gelegt wird. Nur so kann Flyo erkennen, ob ein Datensatz neu ist, geändert wurde oder unverändert geblieben ist.

Allgemeine Anforderungen an die Quelle

Damit eine Quelle mit der Import Integration verwendet werden kann, sollte sie die folgenden Anforderungen erfüllen:

• Die Quelle muss über eine öffentliche https://-URL erreichbar sein.
• Die URL muss beim Abruf erfolgreich antworten.
• Als Format werden insbesondere CSV und JSON unterstützt.
• Die Struktur der Daten muss konsistent sein, damit Flyo Spalten und Werte sauber zuordnen kann.
• Jeder Datensatz muss ein eindeutiges und stabiles Identifier-Feld enthalten.

Dieser Identifier ist besonders wichtig. Er darf sich für denselben Datensatz nicht bei jedem Export ändern. Geeignet sind zum Beispiel externe IDs, ERP-IDs, Event-IDs, Produktnummern oder andere dauerhafte Schlüssel aus dem Quellsystem.

Anforderungen an die Struktur

Für alle Quellen gilt:

• Jeder Datensatz muss als eigenständige Zeile oder als eigenes Objekt vorliegen.
• Alle Datensätze sollten dieselbe Grundstruktur haben.
• Pflichtfelder sollten nicht nur gelegentlich, sondern möglichst durchgehend vorhanden sein.
• Leere oder wechselnde Spaltennamen erschweren den Import und sollten vermieden werden.

Für CSV gilt zusätzlich:

• Die erste Zeile sollte eine Header-Zeile mit klaren Spaltennamen enthalten.
• Eine dieser Spalten muss den eindeutigen Identifier enthalten.
• Die Datei sollte als vollständiger Export der gewünschten Datensätze bereitgestellt werden.

Für JSON gilt zusätzlich:

• Die Daten sollten als Liste von Objekten bereitgestellt werden.
• Jedes Objekt sollte dieselben zentralen Keys enthalten.

Anforderungen an den Identifier

Der Identifier muss:

• pro Datensatz eindeutig sein,
• dauerhaft stabil bleiben,
• nicht zufällig pro Export neu erzeugt werden,
• für denselben Eintrag immer denselben Wert liefern.

Flyo mappt diesen Wert auf source_id. Fehlt dieser Wert oder ändert er sich laufend, kann Flyo Datensätze nicht mehr korrekt verfolgen.

Pagination

Wenn die Quelle viele Datensätze enthält, sollte die Bereitstellung vorab sauber geplant werden:

• Bei JSON kann Pagination verwendet werden.
• Empfohlen sind HTTP-Link-Header mit rel="next", damit Folgeseiten automatisch geladen werden können.
• Die Pagination sollte stabil aufgebaut sein und keine Endlosschleifen erzeugen.
• Bei CSV ist in der Regel ein vollständiger Export über eine einzelne URL sinnvoller als Pagination.

Beispiel für einen Link-Header:

Link: <https://example.org/api/items?page=2>; rel="next"

Anforderungen an JSON-Quellen

JSON ist das empfohlene Format, wenn Daten strukturiert und flexibel bereitgestellt werden sollen.

Eine gültige JSON-Quelle sollte folgende Anforderungen erfüllen:

• Der oberste JSON-Wert ist ein Array.
• Das Array ist nicht leer.
• Jeder Eintrag im Array ist ein Objekt.
• Das erste Objekt enthält bereits die relevanten Keys, damit Flyo die Struktur erkennen kann.
• Jedes Objekt enthält ein stabiles ID-Feld für das Mapping auf source_id.

Nicht geeignet sind zum Beispiel:

• ein leeres Array [],
• ein Array mit primitiven Werten wie ["a", "b"],
• ein einzelnes Objekt statt einer Liste von Datensätzen.

Beispiel für ein gültiges JSON:

[
  {
    "id": "1001",
    "title": "Sommerfestival",
    "starts_at": "2026-08-10T18:00:00.000Z",
    "image": "https://cdn.example.org/images/festival.jpg"
  },
  {
    "id": "1002",
    "title": "Herbstmarkt",
    "starts_at": "2026-10-12T09:30:00.000Z",
    "image": "https://cdn.example.org/images/markt.jpg"
  }
]

Empfohlene Content-Types für JSON:

• application/json
• text/json

Beispiel: Google Spreadsheet als CSV-Quelle verwenden

Eine einfache Möglichkeit für nicht-technische Teams ist es, Inhalte in Google Sheets zu pflegen und das Spreadsheet als CSV-Quelle für Flyo zu veröffentlichen.

Tabelle vorbereiten

Erstelle in Google Sheets eine Tabelle mit einer klaren Header-Zeile, zum Beispiel:

id	title	description	image
evt-1001	Sommerfestival	Open-Air Event im Park	https://example.org/image1.jpg
evt-1002	Herbstmarkt	Markt mit regionalen Produkten	https://example.org/image2.jpg

Wichtig ist dabei:

• Die Spalte id enthält den stabilen eindeutigen Identifier.
• Jede weitere Spalte entspricht einem späteren Mapping-Feld in Flyo.
• Bild- oder Dateispalten sollten direkte https://-URLs enthalten.

Tabelle veröffentlichen

In Google Sheets:

1. Öffne das gewünschte Spreadsheet.
2. Wähle Datei > Freigeben > Im Web veröffentlichen.
3. Wähle das gewünschte Tabellenblatt.
4. Wähle als Format CSV.
5. Veröffentliche das Blatt.

Google Sheets erzeugt danach eine öffentliche CSV-URL.

Sie sieht typischerweise so aus:

https://docs.google.com/spreadsheets/d/e/EXAMPLE/pub?gid=0&single=true&output=csv

Diese veröffentlichte CSV-URL kann direkt als Import-Quelle in Flyo verwendet werden. Dadurch lassen sich Inhalte auch ohne eigene API automatisiert aus einem Spreadsheet nach Flyo importieren.

Wenn das veröffentlichte Google Sheet aktualisiert wird, kann Flyo die Änderungen beim nächsten Importlauf erkennen und den zugehörigen Inhalt aktualisieren oder als Änderungsvorschlag verarbeiten.

Transformationen und Feldanforderungen

Beim Import werden Werte abhängig vom Ziel-Feldtyp verarbeitet. Deshalb sollte die Quelle nicht nur formal korrekt sein, sondern auch inhaltlich passende Werte liefern.

Text und Textarea

• HTML-Tags werden entfernt.
• Der verbleibende Text wird bereinigt.
• Reiner Plain Text ist als Quelle am zuverlässigsten.

Beispiel:

Sommerfestival im Stadtpark

Datumsfelder

Datumswerte sollten im Format YYYY-MM-DD geliefert werden.

Beispiel:

2026-08-10

Datetime-Felder

Datums- und Zeitwerte sollten im ISO-8601-Format geliefert werden.

Beispiel:

2026-04-12T15:30:00.000Z

Bild- und Dateifelder

Für Bild- und Dateifelder gilt:

• Der Wert muss eine gültige URL sein.
• Die URL sollte über https:// erreichbar sein.
• Die URL sollte direkt auf die Datei zeigen.
• Die Datei muss für Flyo beim Import abrufbar sein.

Wenn eine Bild- oder Datei-URL ungültig ist oder der Download fehlschlägt, kann der betroffene Datensatz nicht korrekt verarbeitet werden.

Beispiele:

Bild:

https://storage.flyo.cloud/integrationsgruppe-flyowebseite_7a158241.jpg

Datei:

https://example.org/dokumente/programmheft.pdf

Allgemeine Empfehlungen für saubere Importe

• Liefere möglichst stabile Feldnamen.
• Verändere die Struktur der Quelle nicht ohne Not.
• Verwende für gemappte Felder keine zufällig generierten Werte.
• Teste neue Quellen zuerst mit einer kleinen Datenmenge.
• Stelle sicher, dass Pflichtwerte nicht leer sind.

So bleibt die Synchronisation zwischen Quelle und Flyo langfristig stabil und nachvollziehbar.