Migrations-Guide / Breaking-Changes

Dieser Migration Guide soll Ihnen bei der Umstellung Ihrer Integrationen von Frontend 1.0 auf Frontend 2.0 helfen. Hierbei werden die Breaking-Changes der einzelnen Integrationen aufgezeigt und erklärt. Weitere Informationen zu den einzelnen Integrationen finden Sie in den jeweiligen Knowledgebase Artikeln. Diese enthalten neben einer vollständigen Parameterbeschreibung einen interaktiven Showcase oder ein interaktives Codebeispiel. Daher geht dieser Guide nicht auf die neuen Funktionen der einzelnen Integrationen ein, sondern zeigt wie die bestehende Funktionalität auf die neue Version migriert werden kann. Außerdem wird in diesem Guide nur auf Integrationen eingegangen, bei denen Breaking-Changes aufgetreten sind. Das heißt, wenn die von Ihnen verwendeten Integrationen nicht in diesem Guide aufgeführt sind besteht kein Handlungsbedarf.

Bevor in den folgenden Abschnitten auf die einzelnen Integrationen eingegangen wird, folgt in diesem Abschnitt eine Beschreibung der allgemeinen Änderungen, die für alle Integrationen gelten.

Plural-Parameter

Parameternamen, welche im Plural sind, verhalten sich auch so. Das bedeutet, dass Sie hier mehrere Werte angeben können, die entweder durch ein Komma (,) oder Pipe (|) getrennt sind. Die Angabe der Werte erfolgt ohne Leerzeichen.

Promise-Handling

Integrationen, die einen completionHandler und emptyResultHandler angeboten haben, geben nun ein Promise zurück. Dieses wird erfolgreich aufgelöst in den Fällen, in denen zuvor der completionHandler aufgerufen wurde und es wird in den Fällen als fehlerhaft markiert, in denen früher der emptyResultHandler aufgerufen wurde.

Das nachfolgende Beispiel zeigt die Verwendung des neuen Promise-Handlings:

oxomi.embedCatalog({
    catalog: 'CODE-123',
    target: '#output',
    completionHandler: function (json) {
        console.log("Artikel gefunden");
    },
    emptyResultHandler: function (json) {
        console.log("Keinen Artikel gefunden.");
    }
});

oxomi.embedDocument({
    document: 'CODE-123',
    target: '#output',
}).then((json) => {
    console.log("Artikel gefunden");
}).catch((json) => {
    console.log("Keinen Artikel gefunden.");
});

Browser-History / Deeplink-Funktion

Das neue History-Handling (oxDeeplink) kann innerhalb der oxomi.initmit dem Parameter disableOverlayHistory deaktiviert werden. Dazu muss der Parameter auf true gesetzt werden.

Abwärtskompatibilität

Viele der neuen Integrationen funktionieren übergangsweise auch mit den alten Parameternamen. Es wird jedoch empfohlen, die neuen Parameternamen zu verwenden, um zukünftige Änderungen zu erleichtern. Ob für Sie hier Handlungsbedarf besteht, können Sie ganz einfach mithilfe der Browser-Konsole überprüfen. Zeigt diese Warnungen, welche mit [OXOMI Legacy Bridge] beginnen, an, sollten Sie die Integrationen anpassen, indem Sie die innerhalb der Warnung vorgeschlagenen Änderungen vornehmen.

Die Integration oxomi.portalSearch wurde umbenannt in oxomi.universalSearch.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.portalSearch = function (args) {
    oxomi.universalSearch(args);
}

Parameter

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.universalSearch Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.universalSearch Integration umbenannten Parameter.

Die Integration oxomi.openPortalSearch wurde umbenannt in oxomi.openUniversalSearch.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.openPortalSearch = function (args) {
    oxomi.openUniversalSearch(args);
}

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.openPortal Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.openPage Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.news Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die Integration oxomi.catalogBrands wurde vollständig durch die neue oxomi.universalSearch Integration ersetzt. Hierfür muss der Parameter displayedResults: documents verwendet werden, um die Universal Search auf die Anzeige von Dokumenten einzuschränken.

Die Integration oxomi.catalogs wurde umbenannt in oxomi.documents.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.catalogs = function (args) {
    oxomi.documents(args);
}

Parameter

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.documents Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.documents Integration umbenannten Parameter.

Die Integration oxomi.catalogsWithDownload wurde vollständig durch die neue oxomi.documents Integration ersetzt. Hierfür muss der Parameter showActions: true verwendet werden.

Die Integration oxomi.catalogsWithLanguages wurde vollständig durch die neue oxomi.documents Integration ersetzt. Hierfür muss der Parameter showAdditionalLanguages: true verwendet werden.

Die Integration oxomi.embedCatalog wurde umbenannt in oxomi.embedDocument.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.embedCatalog = function (args) {
    oxomi.embedDocument(args);
}

Parameter

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedDocument Integration umbenannten Parameter.

Die Integration oxomi.embedCatalogWithDownload wurde vollständig durch die neue oxomi.embedDocument Integration ersetzt. Hierfür muss der Parameter showActions: true verwendet werden.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedDocument Integration umbenannten Parameter.

Die Integration oxomi.embedCatalogWithLanguages wurde vollständig durch die neue oxomi.embedDocument Integration ersetzt. Hierfür muss der Parameter showAdditionalLanguages: true verwendet werden.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedDocument Integration umbenannten Parameter.

Die Integration oxomi.openCatalog wurde umbenannt in oxomi.openDocument.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.openCatalog = function (args) {
    oxomi.openDocument(args);
}

Parameter

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.news Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedDocument Integration umbenannten Parameter.

Die Integration oxomi.downloadCatalog wurde umbenannt in oxomi.downloadDocument.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.downloadCatalog = function (args) {
    oxomi.downloadDocument(args);
}

Parameter

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedDocument Integration umbenannten Parameter.

Die Integration oxomi.videoBrands wurde vollständig durch die neue oxomi.universalSearch Integration ersetzt. Hierfür muss der Parameter displayedResults: videos verwendet werden, um die Universal Search auf die Anzeige von Videos einzuschränken.

Die Integration oxomi.videos behält ihren Namen oxomi.videos.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.videos Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.videos Integration umbenannten Parameter.

Die Integration oxomi.embedVideo behält ihren Namen oxomi.embedVideo.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedVideo Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedVideo Integration umbenannten Parameter.

Die Integration oxomi.openVideo behält ihren Namen oxomi.openVideo.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.openVideo Integration umbenannten Parameter.

Die Integration oxomi.galleryBrands wurde vollständig durch die neue oxomi.universalSearch Integration ersetzt. Hierfür muss der Parameter displayedResults: galleries verwendet werden, um die Universal Search auf die Anzeige von Exposés einzuschränken.

Die Integration oxomi.galleries behält ihren Namen oxomi.galleries.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.galleries Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.galleries Integration umbenannten Parameter.

Die Integration oxomi.embedGallery behält ihren Namen oxomi.embedGallery.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.embedGallery Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die Integration oxomi.stories behält ihren Namen oxomi.stories.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.stories Integration umbenannten Parameter.

Dokumentseiten - oxomi.itemPages

Ersetzt durch oxomi.productData mit Informationstyp pages. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Dokumentseiten (mit Download-Button) - oxomi.itemPagesWithDownload

Ersetzt durch oxomi.productData mit Informationstyp pages und Parameter showActions: true. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Bilder - oxomi.itemImages

Ersetzt durch oxomi.productData mit Informationstyp product-images. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Videos - oxomi.itemVideos

Ersetzt durch oxomi.productData mit Informationstyp videos. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Exposes - oxomi.itemGalleries

Ersetzt durch oxomi.productData mit Informationstyp galleries. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Dateien - oxomi.itemAttachments

Ersetzt durch oxomi.productData mit Informationstyp attachments. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Langtext - oxomi.itemText

Ersetzt durch oxomi.productData mit Informationstyp html-description. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Artikelbeziehungen - oxomi.itemReferences

Ersetzt durch oxomi.productData mit Informationstyp relationships. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Datenblatt - oxomi.itemDatasheet

Die Integration oxomi.itemDatasheet wurde umbenannt in oxomi.productDatasheet.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.itemDatasheet = function (args) {
    oxomi.productDatasheet(args);
}

Parameter

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.productDatasheet Integration entfallenen Parameter und erklärt, wie diese ersetzt werden können, sofern nötig.

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.productDatasheet Integration umbenannten Parameter.

Datenblatt öffnen - oxomi.openProductDatasheet

Die nachfolgende Tabelle beschreibt die in der FE 2.0 oxomi.openProductDatasheet Integration umbenannten Parameter.

Datenblatt-PDF-Download - oxomi.downloadItemDatasheet

Entfällt als aufrufbare Einzel-Integration, da es im Datenblatt integriert ist.

Stammdaten - oxomi.itemMasterdata

Ersetzt durch oxomi.productData mit Informationstypen header und commercial. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Datenverfügbarkeit - oxomi.exists

Ersetzt durch oxomi.productDataExists. Ein Aufruf ist aber nun oftmals nicht mehr nötig, da ein gesammelter Aufruf an oxomi.productData abgesetzt werden kann.

Merkmale - oxomi.itemFeatures

Ersetzt durch oxomi.productData mit Informationstyp features. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

Bauphasen - oxomi.itemInformationPerPhase

Ersetzt durch oxomi.productData mit Informationstyp building-phases. Mehrere Anfragen für ein Produkt können nun in einem Aufruf gebündelt werden.

3D-Viewer - oxomi.item3dViewer

Die Integration oxomi.item3dViewer wurde umbenannt in oxomi.product3dViewer.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.item3dViewer = function (args) {
    oxomi.product3dViewer(args);
}

3D-Modell-Verfügbarkeitsprüfung - oxomi.item3dExists

Die Integration oxomi.item3dExists wurde umbenannt in oxomi.product3dExists.

Abwärtskompatibilität

Durch die Umbenennung der Integration ist es notwendig, dass Sie diese auch in Ihrer Anwendung umbenennen. Sollten Sie diese Anpassungen derzeit nicht vornehmen können, stellt die Verwendung einer Legacy-Bridge eine mögliche Lösung dar. Das nachfolgende Codebeispiel zeigt, wie Sie diese bauen können. Es wird empfohlen, dass Sie die Legacy-Bridge direkt vor dem Aufruf der oxomi.init Funktion einfügen.

oxomi.item3dExists = function (args) {
    oxomi.product3dExists(args);
}

Die zuvor während der Initialisierung (oxomi.init) angegebenen Callbacks wurden durch eine neuartige Implementierung mittels Buzz ersetzt. Hierbei kann die eigentliche Abfrage-Logik nahezu identisch bleiben, muss aber in die neue Struktur überführt werden. Sehen Sie hierfür am besten die neuen Artikel zu Buzz und Infoplay bzw. die unten verlinkten Alternativen zu den von ihnen verwendeten Funktionen.

Die Datenstruktur der zurück gegebenen Produktinformationen orientiert sich hier sehr stark an den alten Callbacks. Sie müssten sich also nahezu eins zu eins übernehmen lassen.

Einen Einblick in die genaueren Unterschiede des Funktionsaufbaus kann auch ein Blick in unsere Infoplay Integrationsbeispiele zu FE 1.0 und FE 2.0 bieten.

Infoplay 2.0

Die Callbacks infoplayItemLookup, infoplayBasketHandlerund infoplayItemHandler wurden durch eine neue Implementierung mittels Buzz ersetzt.

infoplayItemLookup -> fetchProductData und enhanceProductData

infoplayBasketHandler -> addProductToBasket

Infoplay Direct

Der Callback infoplayProductLookup wurde durch eine neue Implementierung mittels Buzz ersetzt.

infoplayProductLookup -> enhanceProductData