README


_{Entwicklung und Support}	_{TYPO3-Integration}	_{Infodienste-Zertifizierung}

Kommunale Infodienste-Daten aus der Linie6Plus direkt in TYPO3 nutzen.

t3infodienste_light synchronisiert kommunale ID-SOAP-XZuFi-Daten in TYPO3 und stellt daraus einen Zuständigkeits- beziehungsweise Behördenfinder bereit. Die Extension ist die TYPO3-Brücke zu den von den Bundesländern bereitgestellten Infodiensten im Verbund Linie6Plus. Sie ist eine kostenfreie Light-Variante von t3infodienste und stellt keinen gleichwertigen kostenlosen Ersatz für die Vollversion dar.

[!IMPORTANT] Vorhandene Landesinfrastruktur statt neuer Datenpflege: Kommunen, die am jeweiligen Infodienste-Angebot ihres Bundeslandes teilnehmen, verfügen bereits über einen Zugang zur redaktionellen Pflege ihrer Verwaltungsinformationen. t3infodienste_light bindet genau diesen gepflegten Datenbestand über die ID-SOAP-XZuFi-Schnittstelle in die kommunale TYPO3-Website ein. Lediglich für den technischen, lesenden Abruf ist ein eigener, kostenfreier und zweckgebundener API-Key erforderlich.

Weitere Hintergründe und Einsatzmöglichkeiten zeigt die Seite Infodienste der Bundesländer mit TYPO3 nutzen.

🧭 Inhaltsverzeichnis

Bereich	Direktzugriff
🚀 Einstieg	Schnellstart · Voraussetzungen · Installation · API-Key
⚙️ Einrichtung und Betrieb	Extension-Konfiguration · Site Set und Frontend · Scheduler und Cronjobs
🧩 Umfang und Anpassung	Funktionsumfang und Grenzen · Templates anpassen
🛡️ Produkt und Hilfe	Zertifizierung · Vollversion · Support · Lizenz

🚀 Einstieg

Schnellstart

Schritt	Was zu tun ist
1. Installieren	`composer require nerdost/t3infodienste-light` und `vendor/bin/typo3 extension:setup` ausführen.
2. Speicher anlegen	Einen Sysfolder für die synchronisierten Datensätze anlegen und die Seiten-ID notieren.
3. API-Key anfordern	Kostenlosen, kommunal gebundenen ID-SOAP-XZuFi-Key bei TSA beantragen.
4. Konfigurieren	`apiUrl`, `storagePid`, `queryid`, `rootOrganisationsId` und `rootGebietId` eintragen.
5. Frontend einrichten	Site Set `nerdost/t3infodienste-light` einbinden, Plugin-Seiten anlegen und die Frontend-PID setzen.
6. Synchronisieren	Scheduler-Cronjob aktivieren, Queue um 02:00 Uhr erzeugen und anschließend alle fünf Minuten verarbeiten lassen.

Die ausführlichen Erläuterungen zu API-Key, Konfiguration, Serveranforderungen, Templates und Zertifizierung folgen in den Abschnitten weiter unten.

Voraussetzungen und Serveranforderungen

TYPO3 13.4 LTS oder ab 14.3
PHP 8.2 bis 8.5, soweit von der eingesetzten TYPO3-Version unterstützt
PHP-Erweiterungen soap, openssl, intl, mbstring und json
MySQL oder MariaDB; der derzeitige Sicherungsablauf verwendet außerdem die Kommandozeilenprogramme mysql, mysqldump und gzip
ein aktiver TYPO3-Scheduler und die Möglichkeit, den TYPO3-CLI-Befehl regelmäßig per System-Cronjob auszuführen
ausgehende HTTPS-Verbindungen zum XZuFi-Endpunkt des Bundeslandes sowie zu https://apilight.t3infodienste.de
Schreibrechte für TYPO3-Logs und das konfigurierte Sicherungsverzeichnis
ausreichend freier Datenbank- und Festplattenspeicher für den vollständigen Datenbestand und komprimierte Sicherungen

Die erste Synchronisierung verarbeitet den vollständigen Datenbestand und benötigt deutlich mehr Laufzeit, Arbeitsspeicher, Netzwerk- und Festplattenkapazität als spätere Aktualisierungen. Für einen stabilen Erstimport werden folgende PHP-Werte empfohlen:

memory_limit = 2048M
max_execution_time = 3600
max_input_time = 3600
default_socket_timeout = 3600
opcache.memory_consumption = 250

Der Erstimport sollte außerhalb der Hauptnutzungszeit per CLI erfolgen. Währenddessen darf t3infodienste_light:primarySync nicht parallel in mehreren Prozessen laufen. Je nach Größe des Landesbestands, Geschwindigkeit des XZuFi-Dienstes und Serverleistung kann die erste vollständige Übernahme längere Zeit beanspruchen.

Installation

Die Extension wird über Composer installiert und anschließend im TYPO3-Backend aktiviert:

composer require nerdost/t3infodienste-light
vendor/bin/typo3 extension:setup

Legen Sie einen Sysfolder für die synchronisierten Infodienste-Datensätze an. Seine Seiten-ID wird sowohl für den Import als auch für die Frontend-Abfragen benötigt.

Kostenlosen TELEPORT-API-Key anfordern

Der API-Key für die Schnittstelle ist nicht mit dem vorhandenen Benutzerzugang zum Infodienste-Redaktionssystem des Bundeslandes identisch. Für die Synchronisierung benötigt die Kommune einen kostenlosen, an Kommune und Einsatzzweck gebundenen API-Key für ID SOAP XZuFi. Die Kommune, in der t3infodienste_light eingesetzt werden soll, muss diesen Schlüssel selbst bei TSA anfordern.

Die Anfrage sollte enthalten:

den vollständigen Namen der Kommune beziehungsweise Verwaltung;
die ausdrückliche Angabe, dass t3infodienste_light eingesetzt wird;
die Bitte um einen API-Key für die lesende Nutzung von ID SOAP XZuFi;
das verwendete Bundesland beziehungsweise Zielsystem.

Empfohlener Betreff:

API-Key-Anfrage ID SOAP XZuFi für t3infodienste_light – [Kommune]

Die Anfrage kann an support@teleport.de gesendet werden. Weitere technische Informationen stehen im offiziellen Portal zu ID SOAP XZuFi und im Bereich Zertifizierung bereit.

Nach Erhalt wird der API-Key in der Extension-Konfiguration im Feld queryid hinterlegt. Der API-Key darf nicht veröffentlicht, in ein Repository eingecheckt oder für eine andere Kommune beziehungsweise einen anderen Einsatzzweck wiederverwendet werden.

⚙️ Einrichtung und Betrieb

Extension konfigurieren

Die Einstellungen befinden sich im TYPO3-Backend unter Admin Tools > Settings > Extension Configuration > t3infodienste_light.

Extension-Konfiguration von t3infodienste_light

Erforderliche Einstellungen

Feld	Bedeutung
`apiUrl`	WSDL-URL des ID-SOAP-XZuFi-Dienstes. Das Bundesland-Kürzel in der URL muss zum Zielsystem passen, zum Beispiel `mv` in `https://xzufi-v2-2-0-mv.zfinder.de/?wsdl` für Mecklenburg-Vorpommern. Die konkrete URL stellt TSA beziehungsweise das Bundesland bereit.
`storagePid`	Seiten-ID des Sysfolders, in den die synchronisierten Datensätze geschrieben werden.
`queryid`	Kostenloser API-Key, der bei TSA durch die einsetzende Kommune angefordert wurde.
`rootOrganisationsId`	ID der obersten Organisationseinheit, auf deren Verwaltungsbereich der Import begrenzt wird.
`rootGebietId`	ID des primären Gebiets, beispielsweise der Stadt, Gemeinde oder des Landkreises.

rootOrganisationsId und rootGebietId sind der Infodienste-Redaktionsoberfläche des jeweiligen Bundeslandes zu entnehmen. Für Mecklenburg-Vorpommern ist dies beispielsweise oauth-mv.infodienste.de. Verwenden Sie jeweils die IDs der für die Zielkommune vorgesehenen Root-Objekte.

ApiLight und optionale Einstellungen

Feld	Bedeutung
`mappingApiUrl`	Endpunkt für das zentrale Light-Mapping. Standard: `https://apilight.t3infodienste.de/instructions`.
`mappingApiTimeout`	Zeitlimit für den Abruf der Mapping-Anweisungen in Sekunden. Standard: `20`.
`backupPath`	Optionaler absoluter Pfad für Datenbanksicherungen.
`logPath`	Optionaler absoluter Pfad für zusätzliche Protokolldateien.
`debugLogging`	Schreibt bei Bedarf ausführlichere Diagnoseinformationen; im Regelbetrieb deaktiviert lassen.
`showAllTables`	Blendet bei Bedarf zusätzliche synchronisierte Tabellen im Backend-Modul ein.

Die Light-Version muss apilight.t3infodienste.de erreichen können, um externe Anweisungen zur Umwandlung der XZuFi-Objekte abzurufen. Das Regelprofil wird lokal zwischengespeichert; die XZuFi-Fachdaten selbst werden lokal in TYPO3 verarbeitet und nicht zur Umwandlung an ApiLight übertragen. In der Vollversion können die Mapping-Regeln projektbezogen selbst festgelegt und ohne Abhängigkeit von der Light-API betrieben werden.

Bei bereits eingerichteten Installationen muss ein zuvor ausdrücklich gespeicherter alter mappingApiUrl-Wert manuell auf den aktuellen Endpunkt geändert werden; neue Defaults überschreiben keine bestehende TYPO3-Extension-Konfiguration.

Die im Backend-Modul freiwillig hinterlegbaren Angaben zu Kommune und technischem Ansprechpartner werden nur nach einer gesonderten Zustimmung an ApiLight übermittelt. Die Zustimmung zum Erhalt von Neuigkeiten und Angeboten ist separat, freiwillig und widerrufbar.

Site Set und Frontend einrichten

Für TYPO3 13 und 14 steht das Site Set t3infodienste Light mit dem technischen Namen nerdost/t3infodienste-light bereit. Es bindet das benötigte Frontend-TypoScript ein und stellt Templatepfade, Datensatz-Speicherseite, CSS-Schalter und Sitemap-Einstellungen als typisierte Site Settings zur Verfügung.

Wählen Sie unter Site Management > Sites in der gewünschten Site das Set nerdost/t3infodienste-light aus.
Setzen Sie unter Settings insbesondere plugin.tx_t3infodienstelight.persistence.storagePid auf den Sysfolder mit den synchronisierten Datensätzen.
Legen Sie Seiten für die benötigten Plugins an und konfigurieren Sie gegebenenfalls die Detailseiten und Sitemap-Typen.
Deaktivieren Sie plugin.tx_t3infodienstelight.assets.includeBasicCss, wenn das Projekt die vollständige Gestaltung selbst bereitstellt.

Die storagePid in der Extension-Konfiguration bestimmt das Ziel des Imports. Die Site-Setting-PID bestimmt, aus welchem Sysfolder das Frontend liest. In der üblichen Installation zeigen beide Werte auf denselben Sysfolder.

Für Bestandsinstallationen bleibt die Einbindung über den statischen TypoScript-Datensatz verfügbar. Pro Site sollte entweder das Site Set oder das klassische statische Template verwendet werden, nicht beides gleichzeitig.

Scheduler und Cronjobs

TYPO3 muss den Scheduler regelmäßig ausführen. Ein typischer System-Cronjob startet ihn einmal pro Minute; Pfad und PHP-Binary sind an das Hosting anzupassen:

* * * * * /usr/bin/php /pfad/zum/projekt/vendor/bin/typo3 scheduler:run

Legen Sie anschließend im TYPO3-Modul System > Scheduler diese Tasks als Execute console commands an:

Command	Empfohlener Zeitplan	Aufgabe
`t3infodienste_light:createQueue`	`0 2 * * *`	Startet täglich um 02:00 Uhr einen neuen Synchronisationslauf und erzeugt die in Teilaufgaben gegliederte Queue.
`t3infodienste_light:primarySync`	`/5 * * *`	Verarbeitet alle fünf Minuten den jeweils nächsten Queue-Schritt.
`t3infodienste_light:cleanUpCommand 30`	`30 1 * * *`	Entfernt täglich um 01:30 Uhr Sicherungsdateien, die älter als 30 Tage sind. Dieser Task ist optional.

Wichtig: Konfigurieren Sie primarySync nur einmal und verhindern Sie über das Hosting ebenfalls parallele Aufrufe. Eine neue Queue sollte nicht erzeugt werden, solange ein vorheriger vollständiger Lauf noch arbeitet. Status, Datenbestand, Umgebungshinweise und Protokolle sind im Backend unter System > Infodienste sichtbar.

🧩 Umfang und Anpassung

Enthaltener Funktionsumfang und Grenzen

Die Light-Version enthält eine Anliegenliste von A bis Z einschließlich Suche, Gebietsfilter und lokaler Liste, Anliegen-Detailansichten mit zuständigen Stellen und Kontaktdaten, Lebenslagenlisten und -details, XML-Sitemaps sowie ein Backend-Dashboard für Systemstatus und Synchronisationsprotokoll.

Die beiden folgenden Seiten der öffentlichen t3infodienste-Demo veranschaulichen die Funktionen, die auch in der Light-Version enthalten sind. Gestaltung, Inhalte und weitere Funktionen der Vollversions-Demo können von einer Light-Installation abweichen:

Die Light-Version stellt keine eigenständigen Listen-, Detail-, Sitemap- oder Suchindexansichten für Organisationseinheiten, Personen, Zuständigkeiten und Onlinedienste bereit. Die betreffenden Daten werden dennoch synchronisiert und können innerhalb der mitgelieferten Anliegen-Detailansicht erscheinen.

Light-Version	Vollversion
Fest vorgegebener Modell- und Relationsumfang	Deutlich größerer Modell-, Relations- und Funktionsumfang
Finale Models, die nicht durch Vererbung erweitert werden können	Models können in einer eigenen Extension durch Vererbung erweitert werden
Zentrale Mapping-Anweisungen über ApiLight	Eigene Mapping-Kontrolle ohne Abhängigkeit von der Light-API
Anliegen- und Lebenslagenansichten im Standardumfang	Zusätzliche Organisations-, Personen-, Zuständigkeits- und Onlinedienstansichten
Vorgegebene Synchronisations- und Ausgabelogik	Projektspezifische Filter, Integrationen und Datenverarbeitung
Lesender Import	Projektspezifisch auch mehrsprachige und bidirektionale Lösungen

Die Modifikation und projektbezogene Bereitstellung eigenständiger Ansichten für weitere Datenarten erfordert eine fachliche und technische Abnahme durch die Nerdost GmbH. In der kostenlosen Light-Version fehlen diese Ansichten bewusst, um einen kostenlosen, möglichst bedenkenlosen Einsatz im klar definierten Standardumfang ohne unkontrollierte funktionale Änderungen und daraus entstehende Abnahmerisiken zu ermöglichen.

Templates an das Zielsystem anpassen

Die bereitgestellten Fluid-Templates dürfen und sollen visuell sowie strukturell an die Site-Extension und das Designsystem des Zielprojekts angepasst werden. Die Extension liefert unter Resources/Private/:

Templates/Anliegen/List.html – Anliegenliste A bis Z;
Templates/Anliegen/Show.html – Anliegen-Detailansicht;
Templates/Anliegen/Suche.html – Suche;
Templates/Anliegen/Gebietsfilter.html – Gebietsfilter;
Templates/Anliegen/ListLokal.html – lokal begrenzte Liste;
Templates/Anliegen/Sitemap.xml – Anliegen-Sitemap;
Templates/Anliegenkategorie/List.html und Show.html – Lebenslagenliste und -detail;
Templates/Anliegenkategorie/Sitemap.xml – Lebenslagen-Sitemap;
unterstützende Templates für Anliegengruppen sowie wiederverwendbare Partials für Anliegen, Lebenslagen, Kontakt- und Zuständigkeitsinformationen;
Layouts/Default.html – gemeinsames Frontend-Layout.

Kopieren Sie nur die tatsächlich angepassten Dateien in Ihre Site-Extension und behalten Sie dort dieselbe Unterverzeichnisstruktur bei. Höher priorisierte Pfade können beispielsweise in der Site-Extension gesetzt werden:

plugin.tx_t3infodienstelight.view {
  templateRootPaths.200 = EXT:site_package/Resources/Private/Extensions/T3InfodiensteLight/Templates/
  partialRootPaths.200 = EXT:site_package/Resources/Private/Extensions/T3InfodiensteLight/Partials/
  layoutRootPaths.200 = EXT:site_package/Resources/Private/Extensions/T3InfodiensteLight/Layouts/
}

Ersetzen Sie site_package durch den Extension-Key Ihrer Site-Extension. Die Priorität .200 liegt über den mitgelieferten Standardpfaden und den Site Settings.

🛡️ Produkt, Zertifizierung und Hilfe

Zertifizierung und projektspezifische Anpassungen

Die Models, Relationen, Mapping-Regeln und fachlichen Ansichten bilden einen abgestimmten Standard. Sie sollten in der Light-Version nicht funktional erweitert oder in ihrer Bedeutung verändert werden, da sich eine vorhandene Abnahme immer auf einen konkreten Funktions- und Ausgabestand bezieht. Änderungen an Models, Mapping, Relationen oder fachlich erforderlichen Ausgaben können deshalb eine erneute Prüfung beziehungsweise Abnahme notwendig machen.

Das bedeutet nicht, dass TSA pauschal jede Quellcodeänderung als automatischen Entzug einer Zertifizierung wertet. Übliche Anpassungen der mitgelieferten Fluid-Templates – etwa HTML-Struktur, CSS-Klassen, barrierearme Bedienung und Einbindung in das projektspezifische Layout – sind ausdrücklich vorgesehen. Dabei müssen die fachliche Aussage, die erforderlichen Inhalte und die Beziehungen der Daten erhalten bleiben. Die Verantwortung für Barrierefreiheit, Gestaltung und korrekte Einbindung im Gesamtsystem liegt beim jeweiligen Projekt.

Wenn neue Models, veränderte Relationen, eigene Mapping-Regeln oder zusätzliche fachliche Ansichten benötigt werden, sollte die Umsetzung mit Nerdost abgestimmt oder die Vollversion eingesetzt werden.

Die Vollversion von t3infodienste

Die Vollversion eignet sich für Projekte, die über den festen Light-Umfang hinausgehen. Dazu gehören unter anderem:

eigenständige Ansichten für Organisationseinheiten, Ansprechpersonen und Onlinedienste;
erweiterbare Models und zusätzliche Relationen;
lokal definierte Mapping-Regeln und projektspezifische Datenumwandlungen;
individuelle A–Z-Listen, Such-, Filter- und Detailkonzepte;
mehrsprachige oder bidirektionale Integrationen nach Projektanforderung;
begleitete Integration, Wartung, Support und Koordination notwendiger Abnahmen durch Nerdost.

Weitere Informationen finden Sie auf der Seite Infodienste der Bundesländer mit TYPO3 nutzen, auf t3infodienste.de und in der Funktionsübersicht der Vollversion. Für eine Beratung oder ein Angebot nutzen Sie bitte die Kontaktseite.

Support

Nerdost GmbH

Lizenz

GPL-2.0-or-later

nerdost / t3infodienste-light

Package info

Security

Statistics