TYPO3-Verbindung

Voraussetzungen

Vor dem Start bitte klären — fehlt eines davon, bleibt die Einrichtung stecken.

Wie die Verbindung funktioniert

ALLMEDIA.AI spricht TYPO3 über die REST-API der Erweiterung nnrestapi an. Die Authentifizierung läuft über HTTP-Basic-Auth mit einem TYPO3-Backend-Benutzer und einem API-Key.

Die Einrichtung besteht aus zwei Teilen: einmal im TYPO3-Backend (Erweiterungen, Benutzer, API-Key) und einmal in der ALLMEDIA App (Verbindungsdaten, Ablageorte, Kanalzuweisung). Am besten beide Systeme in zwei Browser-Tabs nebeneinander öffnen.

1 Verbindung anlegen und Extension herunterladen

1. Kanalverbindungen öffnen

   In der ALLMEDIA App den richtigen Workspace wählen und in die Einstellungen wechseln.

   Einstellungen → Veröffentlichung → Kanalverbindungen

   

2. Neue Verbindung starten

   Rechts oben auf „Kanal verbinden“ klicken. Es öffnet sich die Auswahl „Kanalverbindungs-Typ auswählen“.

3. TYPO3 auswählen

   Im Suchfeld TYPO3 eingeben und die Kachel TYPO3 — „Inhalte direkt auf TYPO3-Websites veröffentlichen“ anklicken. Der Dialog „Neuer TYPO3 Connector“ öffnet sich.

   Hinweis: Es lassen sich mehrere TYPO3-Verbindungen parallel anlegen, z. B. für mehrere Websites.

   

4. Namen vergeben

   Im Feld Name einen sprechenden Namen eintragen, etwa TYPO3 Unternehmenswebsite. Der Name erscheint später in der Kanalverbindungs-Liste und im Kanal-Workflow.

5. AllMedia-Extension herunterladen

   Im Dialog auf „Extension herunterladen“ klicken (Datei allmedia.zip, ca. 171 KB). Diese Erweiterung liefert die flachen Endpoints /api/news, /api/pages und /api/category, die ALLMEDIA nutzt.

   Pflicht vor allen TYPO3-Schritten. Ohne diese Extension liefert die API keine Daten. Die ZIP-Datei nicht umbenennen — TYPO3 leitet den Extension-Key aus dem Dateinamen ab.

   

2 TYPO3-Backend vorbereiten

Diese Schritte erledigt der TYPO3-Administrator. Die Klick-für-Klick-Anleitung steht im Connector-Dialog ebenfalls unter „So richtest du TYPO3 ein (6 Schritte)“.

1. AllMedia-Extension installieren

   TYPO3-Backend → Erweiterungen → „Upload Extension“

   Die heruntergeladene ZIP unverändert hochladen und aktivieren. Alternativ manuell nach typo3conf/ext/allmedia/ entpacken oder per Composer:

   composer require allmedia/typo3-integration

2. Erweiterungen nnhelpers und nnrestapi installieren

   TYPO3-Backend → Admin-Tools → Erweiterungen → „Get Extensions“

   Nach nnhelpers suchen (Version ≥ 13.1.5) und installieren. Danach dieselbe Suche für nnrestapi. Alternativ als ZIP über „Upload Extension .t3x/.zip“ hochladen.

3. Weg A — Site-Set „ALLMEDIA Integration“ aktivieren

   TYPO3-Backend → Site Management → Sites → Site bearbeiten → Abschnitt „Sets for this Site“

   Im rechten Feld „Available Items“ den Eintrag „ALLMEDIA Integration“ markieren und mit dem Pfeil nach links ins Feld „Selected Items“ verschieben → Save. Das reicht fürs Frontend bzw. die API, weil das Set das nnrestapi-TypoScript automatisch mitbringt; ein manuelles Einbinden über Web → Template entfällt.

   Nach jedem Extension-Update: einmal Admin Tools → Maintenance → „Flush TYPO3 and PHP Cache“ ausführen — sonst erscheint das Set nicht unter „Available Items“. Meldet die Site-Konfiguration INVALID VALUE ('Site set allmedia/allmedia not found'), ist die Extension noch nicht in der aktuellen Version installiert (mindestens 1.0.7).

4. Weg B — TypoScript-Record im Root anlegen

   TYPO3-Backend → Web → List → Root-Seite → Neuer Datensatz → „TypoScript record“

   Zusätzlich nötig für das nnrestapi-Backend-Modul. Symptom, wenn dieser Schritt fehlt: im RestApi-Backend-Modul erscheint „Where's my TypoScript? — No TypoScript configuration found.“ und die API liefert keine Daten.

   So beheben: Neuen TypoScript-Record anlegen → Reiter „Advanced Options“ → Feld „Include TypoScript sets“ → „RestApi Configuration (nnrestapi)“ (und optional „ALLMEDIA Integration“) zu den Selected Items hinzufügen → „Rootlevel“ aktivieren → Speichern → Cache leeren.

   Wichtig: Die Häkchen Clear: Constants und Clear: Setup unbedingt LEER lassen. Sie löschen das vererbte TypoScript-Setup der Rootline inklusive des page = PAGE-Objekts, das Frontend und API zum Rendern brauchen. Ergebnis sonst: HTTP 500 auf / und allen /api/…-Endpoints.

   Weg A reicht für Frontend und API, Weg B ist zusätzlich für das nnrestapi-Backend-Modul erforderlich. In der Praxis ist genau dieser Schritt die häufigste Ursache, wenn „eigentlich alles richtig konfiguriert“ scheint, die API aber leer bleibt.

5. Backend-Benutzer für die API anlegen

   TYPO3-Backend → System → Backend-Benutzer → Neu (oder bestehenden Benutzer bearbeiten)

   Empfohlener Username: allmedia. Dieser Name muss exakt mit dem Feld „API-Benutzer“ in der ALLMEDIA App übereinstimmen. Dem Benutzer eine Gruppe mit nnrestapi-Berechtigung zuweisen.

6. API-Key in der Extension-Konfiguration eintragen

   TYPO3-Backend → Admin Tools → Settings → Extension Configuration → nnrestapi → Tab „basic“

   Im Feld „API-Keys for BasicAuth“ (Schlüssel basic.apiKeys) pro Zeile einen Eintrag im Format benutzername:apikey eintragen, zum Beispiel:

   allmedia:dA8...32Zeichen...Xy

   Der Benutzername muss exakt dem Backend-Benutzer aus dem vorigen Schritt entsprechen. Den API-Key vergibst du selbst (Zufallsstring, mindestens 32 Zeichen) — oder du lässt ihn in der ALLMEDIA App erzeugen (siehe Teil 3). Speichern — fertig.

3 Verbindung in ALLMEDIA herstellen und testen

Zurück im Dialog „Neuer TYPO3 Connector“, Reiter Verbindung.

1. Website-URL eintragen

   Die URL der TYPO3-Website inklusive https://, zum Beispiel https://www.example.com.

2. API-Benutzer eintragen

   Der TYPO3-Backend-Benutzer mit nnrestapi-Berechtigung. Standard und Empfehlung: allmedia.

3. API-Key setzen

   Zwei Wege:

   a) Key in ALLMEDIA erzeugen — auf „Key erzeugen“ klicken. Danach mit „Benutzer:Key kopieren“ die fertige Zeile im Format allmedia:WKxzFa… kopieren und genau so in TYPO3 unter nnrestapi → basic.apiKeys einfügen.

   b) Bestehenden Key verwenden — den in TYPO3 hinterlegten Key direkt ins Feld API-Key eintragen.

   Der Key wird in ALLMEDIA verschlüsselt gespeichert und als HTTP-Basic-Auth an TYPO3 gesendet. Bei einer bestehenden Verbindung ist er ausgeblendet und lässt sich über „Zurücksetzen“ überschreiben.

   

4. Optional: Endpoint-Pfade prüfen

   Unter „Erweitert: Endpoint-Pfade“ stehen die Standardpfade /api/pages und /api/news. Nur ändern, wenn das TYPO3 abweichende Pfade nutzt. Die Pfade sind relativ zur Website-URL und beginnen mit /.

5. Verbindung testen

   Auf „Verbindung testen“ klicken. Bei Erfolg erscheint „Authentifizierung erfolgreich“ und eine Meldung wie „Verbunden · 6 Seiten geladen“.

   Erst wenn der Test grün ist, speichern und mit dem Mapping fortfahren. Ein roter Test bedeutet fast immer: falscher Benutzername, falscher Key oder fehlende TypoScript-Konfiguration.

   

6. Endpoint-Diagnose lesen

   Nach dem Test klappt unterhalb die Endpoint-Diagnose auf. Sie zeigt einzeln, ob nnrestapi erreichbar ist, ob das ALLMEDIA-Plugin installiert ist und welche Endpoints mit OK (200) antworten. Das ist der schnellste Weg zur Ursache, wenn etwas fehlt.

   

7. Speichern

   Mit „Speichern“ abschließen. Die Verbindung erscheint nun in der Liste der Kanalverbindungen mit dem Status Verbunden.

4 Ablageorte und Standards festlegen

Im selben Dialog auf den Reiter Standards wechseln. Hier wird festgelegt, wohin ALLMEDIA die Inhalte in TYPO3 schreibt.

1. Ablageorte laden

   Auf „Aktualisieren“ klicken. ALLMEDIA liest den Seitenbaum aus; darunter erscheint die Anzahl der gefundenen Einträge mit Zeitstempel.

2. News-Beiträge → Ablageordner

   Den Sysfolder wählen, in dem News-Datensätze liegen, z. B. News (UID 2).

3. Standard-Seiten → Zielseite

   Die Seite wählen, unter der neue Unterseiten angelegt werden, z. B. Blog (UID 1).

   Hintergrund: In TYPO3 werden Beiträge wie News oder Blog-Artikel klassisch in einem Ablageordner (intern „Sysfolder“, doktype 254) im Seitenbaum abgelegt — nicht direkt als sichtbare Seite. Klassische Seiten (doktype 1) werden hingegen direkt als Unterseite angelegt. Diese Ordner bzw. Zielseiten müssen im TYPO3-Backend existieren und werden hier ausgewählt.

   

4. Standard-Sprache setzen

   Standardwert ist Default · UID 0. TYPO3 liefert keine Sprach-Liste über die API (kein /api/site-Endpoint) — die UID daher aus dem TYPO3-Backend unter Site-Verwaltung übernehmen.

5. Speichern

   Änderungen mit „Speichern“ übernehmen.

5 Verbindung einem Kanal zuweisen

Eine Kanalverbindung allein veröffentlicht noch nichts. Sie muss im Workflow eines Kanals als Veröffentlichungsziel hinterlegt werden.

1. Kanal öffnen

   Einstellungen → Inhalte & Kanäle → Kanäle → gewünschten Kanal anklicken

   Alternativ direkt aus dem Connector-Dialog über den Reiter „Verknüpfte Kanäle“.

2. In den Workflow-Modus wechseln

   Oben auf „Workflow“ klicken. Die Stationen des Kanals werden als Ablauf dargestellt.

3. Veröffentlichung setzen

   In der Station „Veröffentlichung“ auf „Ändern“ klicken und die TYPO3-Verbindung auswählen. Sie erscheint anschließend als Eintrag in der Station.

   

4. Freigabe prüfen

   In der Station „Freigaben“ steuern, ob Beiträge vor der Veröffentlichung freigegeben werden müssen. Änderungen werden automatisch gespeichert („Gespeichert“ oben rechts).

5. Testbeitrag veröffentlichen

   Einen Testbeitrag über den Kanal veröffentlichen und im TYPO3-Backend prüfen, ob der Datensatz im gewählten Ablageordner liegt.

Feldreferenz

Fehlerbehebung