PIM

Die PIM-Schnittstelle ermöglicht den Export von Produktdaten aus dem Multiflex ERP-System in ein externes PIM-System (Product Information Management). Diese Seite beschreibt nur den Export; der Import von Assets (PimAssetImport) ist nicht Teil dieser Dokumentation.

Die Konfiguration erfolgt im Multiflex Grundlagenmanager und im WpfInterfaces.
Im Multiflex Grundlagenmanager unter dem Punkt „PIM“ werden die Basiseinstellungen für die PIM-Anbindung getroffen.
Im WpfInterfaces erfolgt die Konfiguration der Schnittstelle (Profile, Mappings, Export).

Multiflex Grundlagenmanager

Basis URL, API-Key und Where-Bedingung werden nur angezeigt, wenn als PIM-System „Pimcore“ ausgewählt ist. Artikel, die nicht der Where-Bedingung entsprechen, werden nicht übertragen und im PIM_UPDATE-Eintrag als „außerhalb der Bedingung“ markiert.

Wenn Pimcore aktiviert wird, wird die Infomeldung „DB Update ausführen“ angezeigt. Im Anschluss muss das Multiflex DB Update ausgeführt werden, welches die benötigten Trigger aktiviert. Diese Trigger schreiben bei Änderungen an Artikeldaten Einträge in die Tabelle PIM_UPDATE, die vom PIM-Interface übertragen werden.

WpfInterfaces

Hauptfunktionen

• Profile verwalten: Es können verschiedene Exportprofile angelegt, bearbeitet, dupliziert, gelöscht, importiert und exportiert werden. Ein Profil definiert, welche Daten, Sprachen und Felder exportiert werden.

• Mappings bearbeiten: Für jedes Profil können die Zuordnungen (Mappings) zwischen ERP-Datenbankfeldern und PIM-Feldern angepasst werden.

• Export durchführen: Einzelne Artikel oder alle offenen Änderungen aus PIM_UPDATE können per REST-Schnittstelle an das PIM übertragen werden. Gelöschte Artikel werden im PIM gelöscht. Für einen einzelnen Artikel kann das JSON auch nur als Datei erzeugt werden.

• Statusberichte: Im Autostart wird bei Fehlern ein Statusbericht erstellt, der per E-Mail versendet werden kann.

• Wiederholung: Fehlgeschlagene Übertragungen werden automatisch erneut versucht (MaxRetryCount).

• Dateiformate und Pfade: Die Schnittstelle unterstützt die Konfiguration des Datumsformats sowie eines UNC-Pfads und einer Download-URL für die Ablage und den Zugriff auf exportierte Dateien.

Bedienung

1. Profil auswählen oder anlegen (Reiter „Settings“):
   Wählen Sie ein bestehendes Profil aus oder legen Sie mit „New Profile“ ein neues an. Profile können dupliziert („Duplicate Profile“), gelöscht („Delete Profile“) sowie als JSON-Datei exportiert („Export Profile“) und importiert („Import Profile“) werden. Name und Sprachen werden mit „Save Profile“ gespeichert.

2. Mappings konfigurieren (Reiter „Settings“):
   Mit „Add Table“ bzw. „Add Profiling“ wird ein Table Mapping hinzugefügt, mit „Add Column“ bzw. „Add Constant“ ein Column Mapping. Die Reihenfolge kann mit den Pfeil-Buttons geändert werden; Table Mappings können dupliziert und entfernt werden. Mit „Save All“ werden die Mappings gespeichert.

3. Export starten (Reiter „Manual Transfer“):

   • Einzelartikel: Artikelnummer eingeben und „Transfer“ wählen, um den Artikel direkt an das PIM zu übertragen, oder „Generate Json“, um das JSON des Artikels ohne Übertragung als Datei zu speichern.

   • Gesamtexport: „Transfer All“ überträgt alle offenen Einträge aus PIM_UPDATE.

   • Im Reiter können außerdem DateTime Format, UNC Path, Download URL, Max Degree of Parallelism und Batch Size angepasst werden.

   • Der Export kann automatisch beim Start der Schnittstelle erfolgen (Autostart). Dabei werden alle offenen Einträge aus PIM_UPDATE mit dem Profil aus ProfileInx übertragen (Konfiguration siehe unten).

4. Status und Fehler prüfen:
   Im Autostart wird bei Fehlern ein Statusbericht erstellt und abhängig vom MailLevel per E-Mail versendet. Das Ergebnis jeder Übertragung steht im jeweiligen PIM_UPDATE-Eintrag (siehe Batch und Fehlerbehandlung).

Konfiguration der Schnittstelle (Autostart):

<Pim>
  <!-- Database Configuration -->
  <DB>DB</DB>                       <!-- Example: ML, PROD, TEST -->
  <USER>SYSADM</USER>               <!-- Database user -->
  <PASSWORD>SYSADM</PASSWORD>       <!-- Database password -->

  <!-- General Settings -->
  <Loglevel>Detail</Loglevel>
  <MaxParallelism>4</MaxParallelism>     <!-- Number of concurrent threads (default 10) -->
  <BatchSize>100</BatchSize>             <!-- Number of items per batch (default 100) -->
  <MaxRetryCount>3</MaxRetryCount>       <!-- Retries of a failed transfer (default 3) -->
  <ProfileInx>1</ProfileInx>             <!-- Inx of the mapping profile -->
  <DateTimeFormat>dd.MM.yyyy HH:mm:ss</DateTimeFormat>   <!-- Format of date values -->
  <BaseUncPath>\\SERVER\Share\PIM</BaseUncPath>          <!-- UNC path for converter DownloadUnc -->
  <BaseUrl>https://example.com/pim</BaseUrl>            <!-- Download URL pointing to BaseUncPath -->

  <!-- Mail / Notification Settings -->
  <ProtocolEMail>your.name@example.com</ProtocolEMail>
  <SenderEMail>noreply@example.com</SenderEMail>
  <SmtpServer>smtp.example.com</SmtpServer>
  <SmtpUser>noreply@example.com</SmtpUser>
  <SmtpPassword>your-secure-password</SmtpPassword>
  <MailLevel>All</MailLevel>   <!-- Options: All | ActivityOnly | ErrorsOnly | NoMail -->
</Pim>

Profile

Im WpfInterfaces (PIM-Interface, Reiter „Settings“) können mehrere Profile konfiguriert werden. Ein Profil besteht aus einem Namen, den zu exportierenden Sprachen („Languages“, mit Strichpunkt getrennt, z. B. „DE;EN“) und den Mappings. Sind keine Sprachen angegeben, werden alle Sprachen exportiert. Die Sprachen schränken die Tabellen ARTIKELTEXT und ZUSATZTEXTE ein.

Welches Profil im Autostart und im Reiter „Manual Transfer“ verwendet wird, wird über ProfileInx in der Konfiguration festgelegt.

Mappings

Hier wird der Aufbau des zu generierenden JSONs angegeben. Dabei wird ein Array an JSON-Objekten generiert. Für jeden noch nicht exportierten Artikel aus der PIM_UPDATE Tabelle wird ein Eintrag in diesem JSON-Array erstellt. Dabei wird zwischen Tabellen und Profilierungskriterien unterschieden.

Tabellen

Tabellen werden mit „Add Table“ hinzugefügt. Folgende Tabellen sind verfügbar:

Profilierungskriterien

Für Profilierungskriterien kann pro Kriterium ein eigenes Mapping angelegt werden („Add Profiling“). Dabei sind die Spalten aus der Tabelle ART_PROFKRIT verfügbar, zusätzlich über Präfix die Spalten aus FR_WERTE (Übersetzungen des Werts, eine Liste je Sprache; mit „FR_WERTE-LAENDERKENNZEICHEN-…“ auch die Spalten des Länderkennzeichens der Sprache) und aus KRITSETTINGS (Einstellungen des Kriteriums).

Mappings

JSON Path (pro Table Mapping)

Für jedes Table Mapping kann ein JSON Path hinterlegt werden. Die Pfadelemente werden mit „.“ getrennt. Gibt es diesen Pfad bereits, wird er erweitert, andernfalls wird ein neues JSON-Objekt in diesem Pfad angelegt.

Handelt es sich bei der Tabelle um eine 1:N-Beziehung (mehrere Einträge pro Artikel), muss ein JSON Path angegeben werden. Für jeden Eintrag wird ein eigenes JSON-Objekt angelegt, und anstelle eines JSON-Objekts wird in diesem Pfad ein JSON-Array erstellt.

Ist der JSON Path leer (nur bei 1:1-Tabellen möglich), werden die Felder direkt ins Root-Element dieses Artikels geschrieben.

Wenn ein Array erzeugt werden soll, obwohl nur ein Eintrag vorhanden ist, kann dies mit eckigen Klammern erzwungen werden (z. B. „attributes[]“).

Filter

Es ist auch möglich, ein bereits bestehendes JSON-Objekt eines Arrays zu erweitern. Über einen Selektor in eckigen Klammern wird festgelegt, in welches Element des Arrays geschrieben wird:

• name[] – neues Element im Array (bei 1:N-Tabellen erhält jeder Datensatz sein eigenes Element)

• name[3] – Element mit dem angegebenen Index (beginnend bei 0); das Array wird bei Bedarf erweitert

• name[_] – alle bereits vorhandenen Elemente des Arrays

• name[feld=SPALTE] – Element, dessen Feld „feld“ dem Wert der Spalte entspricht

• name[feld='Text'] – Element, dessen Feld „feld“ dem angegebenen Text entspricht

In den eckigen Klammern kann eine Bedingung „feld=WERT“ angegeben werden: „feld“ ist ein Feld der JSON-Objekte im Array, „WERT“ ist eine Spalte oder ein Text in Hochkommas. Gibt es noch kein passendes Element, wird es angelegt (mit dem Feld „feld“). Um auch konvertierte Werte richtig zu vergleichen, wird der Converter des Mappings auf die Spalte angewendet, bevor der Vergleich durchgeführt wird.

Als Spalte kann auch eine Spalte einer verknüpften Tabelle mit Präfix angegeben werden, z. B. „localizedfields[language=LAENDERKENNZEICHEN-ISO]“. Ist die verknüpfte Tabelle eine Liste (z. B. FR_WERTE bei Profilierungskriterien), wird für jeden Eintrag ein eigenes Element ausgewählt bzw. angelegt, und in jedes Element werden nur die Werte dieses Eintrags geschrieben.

Mit „_“ in den eckigen Klammern (z. B. „assets[_]“) werden die Werte in alle bereits vorhandenen Elemente des Arrays geschrieben. Gibt es noch keine Elemente, wird nichts geschrieben. Selektoren können in jedem Pfadelement verwendet werden, z. B. „assets[_].metadata[name='title']“.

Column Mappings

Für jedes Column Mapping muss ein JSON Path angegeben werden, in welches Feld der Wert geschrieben wird. Es kann auch ein mehrstufiger JSON Path angegeben werden, um eine verschachtelte Struktur zu erzeugen (z. B. „values.name“); in den vorderen Pfadelementen sind dieselben Selektoren wie beim Table Mapping möglich. Das letzte Pfadelement muss ein einfacher Feldname ohne eckige Klammern sein. Wird dasselbe Feld mehrfach befüllt, bricht die Generierung des Artikels mit einem Fehler ab.

Es kann entweder eine Spalte („Add Column“) oder eine Konstante („Add Constant“) angegeben werden. Eine Konstante ist ein statischer Text, der in das Feld geschrieben wird.

Null-Werte werden als null in das JSON geschrieben. Datumswerte werden im eingestellten DateTimeFormat ausgegeben.

Spalten verknüpfter Tabellen (siehe Tabellen) werden mit dem Tabellennamen als Präfix angegeben, z. B. „LAENDERKENNZEICHEN-ISO“. Präfixe können verkettet werden, z. B. „FR_WERTE-LAENDERKENNZEICHEN-ISO“. Gibt es den verknüpften Datensatz nicht, wird das Feld nicht geschrieben. Ist die verknüpfte Tabelle eine Liste (z. B. FR_WERTE), sollte das Zielelement über eine Bedingung im JSON Path ausgewählt werden (siehe Filter), damit jeder Eintrag in ein eigenes Element geschrieben wird.

Zusätzlich kann ein Converter angegeben werden. Dieser ermöglicht die Veränderung von Werten, bevor diese ins JSON-Feld geschrieben werden. Beim Converter „Fallback“ wird ein weiteres Auswahlfeld für die Fallback-Spalte angezeigt.

Batch und Fehlerbehandlung

Über BatchSize und MaxParallelism kann kontrolliert werden, wie viel gleichzeitig geladen und übertragen wird. Über MaxRetryCount wird festgelegt, wie oft eine fehlgeschlagene Übertragung wiederholt wird.

Das Ergebnis jeder Übertragung wird im jeweiligen PIM_UPDATE-Eintrag gespeichert (Status, Notiz mit der Antwort bzw. Fehlermeldung, Exportdatum):

• Exportiert: Die Übertragung war erfolgreich.

• Außerhalb der Bedingung: Der Artikel entspricht nicht der Where-Bedingung aus den Grundlagen und wird nicht übertragen.

• Exportiert mit Fehler: Die Übertragung ist fehlgeschlagen. Solange MaxRetryCount nicht erreicht ist, wird automatisch ein neuer PIM_UPDATE-Eintrag angelegt, der beim nächsten Lauf erneut übertragen wird. Danach wird eine Warnung protokolliert und kein weiterer Versuch angelegt.

Liegen für einen Artikel mehrere offene Einträge vor (z. B. Neu, Änderung, Löschen), werden diese zu einer Übertragung zusammengefasst. Nach 10 fehlgeschlagenen Verbindungen zum PIM werden im selben Lauf keine weiteren Übertragungen mehr versucht; die betroffenen Einträge werden als fehlerhaft markiert.

Converter

Ein Converter kann pro Column Mapping (und pro Table Mapping) ausgewählt werden. Er verändert den Wert, bevor dieser ins JSON-Feld geschrieben wird. Ein beim Table Mapping angegebener Converter wird auf die Spalten von Bedingungen im JSON Path angewendet (siehe Filter).

DownloadUnc

Nur anwendbar auf Felder der Tabelle „ARTIKELBILDER“. Bei diesem Converter ist die angegebene Column nicht relevant.

Bei Verwendung des Converters wird die Datei an den in den Einstellungen angegebenen UNC-Pfad (BaseUncPath) kopiert und der Pfad durch die angegebene Download-URL (BaseUrl) ersetzt. Die Download-URL muss also eine vom Zielsystem erreichbare Adresse sein und auf den Pfad zeigen, der im UNC-Pfad angegeben ist.

• Ist beim Bild kein Pfad hinterlegt, wird der Pfad aus den Grundlagen verwendet (Artikeldokumente für PDF und MP4, sonst Artikelbilder).

• Ist der Pfad bereits eine URL, wird der Wert unverändert übernommen.

• Existiert die Quelldatei nicht, wird ein Fehler protokolliert und der Wert nicht umgewandelt.

• Existiert im UNC-Pfad bereits eine Datei mit gleichem Namen, aber anderem Inhalt, bricht die Übertragung des Artikels mit einem Fehler ab. Bei gleichem Inhalt wird die Datei nicht erneut kopiert.

PimCoreAssetType

Nur anwendbar auf Felder der Tabelle „ARTIKELBILDER“. Bei diesem Converter ist die angegebene Column nicht relevant.

Der Dateiname des Bildes wird mit den Regeln der Tabelle „PIM_ASSETTYPE_CONVERTER“ verglichen. Die erste passende Regel bestimmt den Wert, der geschrieben wird. Passt keine Regel, wird ein leerer Text geschrieben. Für den Export werden nur Regeln mit TYPE = 1 (Export) oder ohne TYPE verwendet.

Combeenation Service

Wenn in der Konfiguration des Combeenation Service ein Profil (PimProfileInx) des PIM-Interfaces angegeben ist und in den Grundlagen als PIM-System „Pimcore“ ausgewählt ist, wird bei der Anlage eines Artikels durch den Combeenation Service eine direkte Übertragung mit diesem Profil an das PIM durchgeführt. Schlägt die Übertragung fehl, wird dies ins Protokoll geschrieben und die Assets des Artikels werden nicht hochgeladen.

In der Konfiguration des Combeenation Service müssen dazu im Element <PimSettings> folgende Einträge ergänzt werden:

<PimSettings>
  <PimProfileInx>1</PimProfileInx>
  <PimDatetimeFormat>dd.MM.yyyy HH:mm:ss</PimDatetimeFormat>
  <PimUncPath>\\SERVER\Share\PIM</PimUncPath>
  <PimDownloadUrl>https://example.com/pim</PimDownloadUrl>
  <PimWithStackTrace>false</PimWithStackTrace>
</PimSettings>