Pimcore-Integrationsarbeit dreht sich selten um die API selbst. Die Endpunkte sind dokumentiert und sie funktionieren. Was eine produktive Integration zerlegt, ist der Teil, den niemand aufgeschrieben hat: welches System welches Feld besitzt, was passiert, wenn sich der Export aus dem Vorsystem verändert, und wer erfährt, dass der nächtliche Job gescheitert ist.
Das hier ist ein praktischer Leitfaden zu den drei Wegen in Pimcore hinein und aus Pimcore heraus, und zu den Mustern, die nach zwei Jahren noch stehen. Er setzt voraus, dass Sie Pimcore bereits betreiben und entscheiden, wie Sie ERP, Shop, DAM oder Übersetzung anbinden.
Die drei Wege hinein und hinaus
Pimcore bietet den Data Hub, die REST-Webservices und alles, was Sie selbst als Symfony-Controller schreiben. Das sind keine konkurrierenden Optionen, sondern unterschiedliche Werkzeuge.
Der Data Hub ergänzt einen konfigurierbaren GraphQL-Endpunkt. Sie definieren, welche Klassen, welche Felder und welche Rechte ein Endpunkt trägt, und Konsumenten fragen genau das ab, was sie brauchen. Entscheidend ist: Das Schema ist explizit. Ein neues Attribut an einer Klasse wird nicht automatisch veröffentlicht, jemand muss die Data-Hub-Konfiguration öffnen und es entscheiden.
Die REST-Webservices decken Objekt- und Asset-Operationen direkt ab. Sie sind für Schreibvorgänge und Tooling nützlich und die einfachere Wahl, wenn der Konsument ein Skript ist und kein Produkt.
Eigene Controller sind für die Fälle, die beides nicht gut abdeckt: ein Bulk-Endpunkt in genau der Form, die ein Partner erwartet, ein Webhook-Empfänger oder eine Operation, die mehrere Objekte berührt und entweder ganz oder gar nicht durchlaufen darf.
- Data Hub GraphQL: leselastige Konsumenten, Shops, Portale, Partner-Feeds, alles mit unterschiedlichem Feldbedarf je Konsument
- REST-Webservices: Schreibvorgänge, Admin-Tooling, Skripte, Integrationen, die Sie auf beiden Seiten kontrollieren
- Eigene Controller: transaktionale Operationen, partnerspezifische Payload-Formate, Webhook-Endpunkte
Warum GraphQL beim Lesen meist gewinnt
Ein Shop braucht acht Felder. Ein Katalog-Generator braucht zwölf andere. Ein Partner-Feed braucht sechs plus einen berechneten Preis. Mit REST bauen Sie entweder drei Endpunkte oder liefern einen fetten Payload aus, von dem jeder Konsument das meiste wegwirft.
Mit dem Data Hub schickt jeder Konsument die Abfrage, die er braucht. Das reduziert die Payload-Größe, aber wertvoller ist die Wirkung auf Änderungen: Ein zusätzliches Feld an einer Klasse verändert nicht mehr, was ein bestehender Konsument bekommt, weil dieser seine Felder ausdrücklich benannt hat.
Der Preis dafür ist Konfiguration. Data-Hub-Endpunkte sind gepflegte Objekte, und es passiert schnell, dass mehrere existieren, an deren Einrichtung sich niemand erinnert. Benennen Sie sie nach dem Konsumenten und nicht nach den Daten, und halten Sie fest, wer für welchen zuständig ist.
ERP-Synchronisation und die vier Regeln, die sie am Leben halten
Hier liegt der Großteil der Pimcore-Datenintegration. Das ERP ist das Vorsystem und besitzt die kaufmännische Wahrheit. Pimcore besitzt den angereicherten Produktdatensatz. Dazwischen bewegt ein zeitgesteuerter Job Daten, und dieser Job ist der fragilste Teil der gesamten Aufstellung.
Vier Regeln entscheiden darüber, ob ein Import jahrelang läuft oder quartalsweise einen stillen Vorfall produziert.
- Legen Sie die Feldhoheit ausdrücklich fest und bilden Sie sie im Code ab. Wenn das ERP Artikelnummer und Preis besitzt, darf Pimcore keiner Redakteurin erlauben, sie zu ändern. Uneindeutige Hoheit ist der Weg, auf dem zwei Systeme beide recht haben und sich trotzdem widersprechen.
- Schlüsseln Sie alles auf eine stabile externe ID, niemals auf die Pimcore-Objekt-ID oder den Objektpfad. Pfade ändern sich, sobald jemand einen Ordner umsortiert, und danach legt Ihr Import von jedem Produkt eine zweite Kopie an.
- Validieren Sie vor dem Schreiben auf Live-Objekte. Datei laden, gegen Erwartungen prüfen (Zeilenzahl in vernünftiger Bandbreite, Pflichtspalten vorhanden, Kodierung intakt), erst danach schreiben. Ein ERP-Export, der stillschweigend die Hälfte seiner Zeilen verliert, muss den Import stoppen und nicht den halben Katalog leeren.
- Machen Sie Fehler laut. Ein Import, der in eine Logdatei scheitert, die niemand liest, ist dasselbe wie kein Import. Melden Sie in den Kanal, den das zuständige Team tatsächlich beobachtet, und liefern Sie genug Kontext zum Handeln mit.
Idempotente Importe in der Praxis
Idempotent heißt: Derselbe Import zweimal ausgeführt hinterlässt dasselbe Ergebnis wie einmal ausgeführt. Das klingt selbstverständlich und wird regelmäßig verletzt, meist von Importen, die anlegen statt zu aktualisieren.
Das Muster lautet: über die externe ID suchen, nur anlegen, wenn nichts gefunden wird, sonst am bestehenden Objekt aktualisieren. Vor dem Schreiben vergleichen, damit ein unveränderter Datensatz keinen neuen Versionseintrag erzeugt. Beim Massenimport das Versioning für die Dauer abschalten und danach wieder aktivieren, sonst wachsen die Versionstabellen schneller als die Daten selbst.
// Upsert über die externe ID, nicht über Pfad oder Objekt-ID.
$product = Product::getByExternalId($row['external_id'], 1);
if (!$product) {
$product = new Product();
$product->setExternalId($row['external_id']);
$product->setParent(Service::createFolderByPath($targetFolder));
$product->setKey(Service::getValidKey($row['external_id'], 'object'));
$product->setPublished(true);
}
// Nur schreiben, wenn sich wirklich etwas geändert hat: eine unveränderte
// Zeile darf nicht bei jedem nächtlichen Lauf eine neue Version erzeugen.
if ($product->getName() !== $row['name']) {
$product->setName($row['name']);
$dirty = true;
}
if ($dirty) {
$product->save();
}Die Fehler, die am meisten kosten
Manche Integrationsprobleme sind teuer, weil sie leise sind. Genau diese lohnt es zu prüfen, wenn Sie eine Instanz übernommen haben.
- Schreiben in lokalisierte Felder ohne Angabe der Sprache, wodurch der Wert in der Locale landet, die der Request-Kontext zufällig getragen hat
- Import bei jeder Änderung im Vorsystem statt zeitgesteuert, wodurch ein arbeitsreicher ERP-Tag zum Lastproblem wird und Fehler kaum reproduzierbar sind
- Aktives Versioning während eines Massenimports, wodurch die Versionstabellen stärker wachsen können als die Nutzdaten
- Ein Data-Hub-Endpunkt mit weiteren Rechten, als der Konsument braucht, meist weil es in der Entwicklung schneller ging und niemand nachgeschärft hat
- Gar keine Überwachung der Verbindung, mit Abstand der häufigste Befund, wenn wir eine übernommene Instanz prüfen
Unklar, was davon auf Ihre Instanz zutrifft? Genau das beantwortet das Audit, zum Fixpreis und in einer Woche.
Pimcore Audit →Übersetzungs- und DAM-Schleifen
Übersetzungssysteme und Asset-Bibliotheken sind ebenfalls Integrationen, und sie haben ein spezifisches Fehlerbild: freigegebene ältere Inhalte überschreiben neuere. Ein Übersetzungsjob geht mit einem Quelltext raus, verbringt zwei Wochen in der Prüfung und kommt zurück, während sich die Quelle geändert hat. Schreibt der Import blind, verschwindet die neuere Änderung.
Die Lösung ist ein Versionsmerkmal, das mit dem Job mitläuft und beim Rücklauf verglichen wird, sowie Konflikte, die an einen Menschen gehen statt still aufgelöst zu werden. Für Assets gilt die entsprechende Regel: Pimcore soll das Asset über seine Identität referenzieren und nicht über eine kopierte Datei, damit am Produkt die freigegebene Fassung hängt.
Wo Sie bei einer fremden Instanz anfangen
Zuerst inventarisieren. Listen Sie jeden zeitgesteuerten Job, jeden Data-Hub-Endpunkt und jede Stelle, an der Zugangsdaten für ein externes System liegen. Bei den meisten übernommenen Instanzen ist diese Liste länger als erwartet, und mindestens ein Eintrag ist ein Rätsel.
Danach die Überwachung prüfen, denn das ist meist die günstigste echte Verbesserung. Eine Integration, die laut scheitert, ist ein beherrschbares Problem. Eine, die still scheitert, ist der Grund, warum irgendwann jemand fragt, warum in einem Markt seit dem Frühjahr drei Produkte fehlen.
Wir bauen und reparieren diese Integrationen für Hersteller in Österreich und Deutschland, auch auf Instanzen, die eine andere Agentur eingeführt hat.
Pimcore Entwicklung und Integration →