# Grundprinzipien Um erfolgreich eine Integration auf Basis der Connect Plattform entwickeln zu können, ist es wichtig folgende Grundprinzipien zu befolgen: ### API Nutzung Als Middleware kommuniziert Connect ausschließlich über die aktuelle REST API mit Xentral ERP. Direkter Zugriff auf die Datenbank oder eine Nutzung der “alten” Xentral APIs ist bei einer Umsetzung über Connect nicht zulässig
* Ausschließlich Nutzung der aktuellen Xentral REST API * Dazu Nutzung des Xentral Connectors im Workflow * Authentifizierung gegenüber der Xentral Instanz im Konnektor über die Methode “Xentral”, keine feste Hinterlegung von Zugangsdaten ### Einfachheit Generell gilt: je einfacher und klarer ein Prozess, desto besser. “Bandwurm”-Prozesse mit mehr als 40-50 Komponenten sind nach Möglichkeit zu vermeiden. Dafür ist es besonders wichtig, dass unterschiedliche “Aufgaben” innerhalb der Schnittstelle (z.B. Bestands- und Preisupdate) auch in unterschiedlichen Workflows abgebildet werden. Es gilt: Eine Aufgabe pro Workflow.
* Prozesse schlank und einfach halten * Eine Aufgabe pro Workflow * Don’t reinvent the wheel: An bestehenden Workflow-Vorlagen orientieren, bewährte Prinzipien übernehmen, gut getestete und funktionierende Workflows oder Teile davon aus anderen Projekten übernehmen * Überflüssige und deaktivierte Komponenten (z.B. Log-Komponenten aus Entwicklung) vor Livegang entfernen Aufgabenteilung Um die Komplexität der zu entwickelnden Schnittstelle zu reduzieren ist eine klare Aufgabenteilung zwischen Connect und ERP-System essentiell. Das bedeutet: Der kanalspezifische Import / Export von Daten sowie die dafür notwendige Transformation der Daten sowie in umgekehrter Richtung die Vorbereitung und Normalisierung der Daten für das Schreiben auf die Xentral-API sind Aufgabe von Connect, die Arbeit mit diesen Daten im Rahmen von ERP-Prozessen sollte ausschließlich in Xentral ERP erfolgen.
* ERP-Logik in Schnittstellenprozessen vermeiden * Datentransformation innerhalb der Workflows transparent dokumentieren ### Xentral als führendes System Nach unserem Prozessverständnis ist Xentral in den meisten Fällen das führende System. Dies trifft insbesondere auf die Artikelanlage sowie die Preis- und Bestandsführung zu. Das bedeutet: Setzt der Kunde beispielsweise ein PIM-System ein, so sollte die Anlage eines Artikels in aller Regel in Xentral erfolgen und die Daten von dort in Richtung PIM synchronisiert werden. SetUps, bei denen Artikel beispielsweise initial im Shop angelegt und von dort zu Xentral synchronisiert werden sind technisch zwar grundsätzlich möglich, widersprechen aber in aller Regel dem Xentral-seitigen Prozessverständnis und können zu Inkompatibilitäten oder erhöhter Komplexität in nachfolgenden Prozessen führen.
* Xentral als führendes System nutzen wenn möglich * Abgleich von Artikeln in Richtung Sales Channel per SKU oder über die Xentral Fremdnummerntabelle ### Sparsame Datenhaltung Grundsätzlich gilt: jede Jobausführung, jeder API-Call und jeder gespeicherte Datensatz kosten verfügbare Serverressourcen und damit Geld und Performance. Alle Workflows sind daher so zu erstellen, dass nur für die jeweilige Aufgabe benötigte Daten abgefragt, gespeichert und weiterverarbeitet werden. Generell sollten Daten aus Xentrral ERP oder dem jeweiligen Sales Channel nur dann auch in Connect zwischengespeichert werden, wenn dies für die Stabilität, Effizienz oder Geschwindigkeit des Prozesse zielführend ist, z.B. bei Berechnung eines Deltas in Connect oder bei asynchronen Updateprozessen.
* Kein Speichern von Daten “auf Verdacht” * Bilder nicht physikalisch zwischenspeichern, sondern Referenz übergeben ### Häufigkeit von Job Executions Die Ausführungshäufigkeit eines Workflows (Number of Job Executions) sollte immer dem jeweiligen Zweck angemessen sein, d.h. Diese sollte zur Änderungshäufigkeit der Daten in Xentral sowie zur benötigten Aktualität der Daten im Verkaufskanal passern. Die Anzahl der auszuführenden Jobs sollte soweit möglich begrenzt werden, ein sehr häufiges Ausführen von Prozessen “auf Verdacht” ist zu vermeiden.
* Nutzung von Event-Triggern statt Cronjobs * Arbeit mit Deltas statt Vollimporten * Gefiltertes Abfragen von List-Endpunkten, z.B. nach Änderungsdatum oder Status ### Errorhandling Connect bietet diverse Möglichkeiten ein intelligentes Errorhandling umzusetzen. So ist es möglich, auf Basis erwartbarer Fehler unterschiedliche Bereiche eines Workflows auszuführen, Fehlermeldungen an den Kunden zu kommunizieren und natürlich mögliche Fehler durch sinnvolle Abfragen und Validierungen proaktiv zu vermeiden.
* Payloads vor Verarbeitung wo nötig validieren * Mögliche Fehler aktiv abfangen (NULL-Werte, fehlende Werte, unerwartete Werte, keine Treffer bei API-Calls, etc.) und transparent ausgeben (Content Identifier, Journal) * Sprechende Fehlermeldungen verwenden --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://connect.xentral.com/guidelines/grundprinzipien.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.