Migration & Integration Guide

Dieser Guide beschreibt die Migration von WebKatalog v1 auf v2(.5) sowie Optimierungen für bestehende v2-Integrationen.

Zusammenfassung

Erstelle eine Planning-URL mit gültigem Token und entweder einem Basis-Artikel (manufacturer/program/basearticlenumber) mit optionalem ocdreinit oder einer permanentid
Bette diese URL als iframe-src in die Kundenwebsite oder den Webshop ein
Migration von v1: Planning-Einstiegspunkt verwenden, Parameter umbenennen, Warenkorb-Handling auf volle Meta-Planungen umstellen
Migration von v2 → v2.5: Hauptsächlich kompatibel, Frontend-Basis-URL anpassen und permanentid-Flows bevorzugen

Basis-URLs

Umgebung	URL	Verwendung
Testsystem	`https://rest.3doffice.de/webkatalog2_5`	Visuelles Frontend
Testsystem	`https://rest.3doffice.de/webkatalog2`	API-Aufrufe
Produktivsystem	`https://web.3doffice.de/webkatalog2_5`	Visuelles Frontend
Produktivsystem	`https://web.3doffice.de/webkatalog2`	API-Aufrufe

Wichtig

Das visuelle Frontend (/planning) befindet sich unter webkatalog2_5. Die API-Endpunkte (xcf.dll, ofml.dll, odb.dll) bleiben unter webkatalog2.

iFrame-Einbindung

Die empfohlene Methode: Baue die Planning-URL serverseitig mit gültigem Token und gewünschten Parametern und rendere sie als iframe-src.

Standard-Artikel-Ansicht

html

<iframe
  width="100%"
  height="800"
  style="border:0"
  src="https://web.3doffice.de/webkatalog2_5/planning?token={TOKEN}&manufacturer=_dx&program=webti&basearticlenumber=27R0614Q&showprice=true&disablecatalogue=false&lang=de&langalt=en">
</iframe>

Spezifische Konfiguration (OCD-only)

html

<iframe
  width="100%"
  height="800"
  style="border:0"
  src="https://web.3doffice.de/webkatalog2_5/planning?token={TOKEN}&manufacturer=_dx&program=webti&basearticlenumber=27R0614Q&ocdreinit={OCD_REINIT}&disablecatalogue=true&showprice=true&lang=de&langalt=en">
</iframe>

Volle Meta-Planung (permanentid)

html

<iframe
  width="100%"
  height="800"
  style="border:0"
  src="https://web.3doffice.de/webkatalog2_5/planning?token={TOKEN}&permanentid={PERMANENT_ID}&disablecatalogue=true&showprice=true&lang=de&langalt=en">
</iframe>

Serverseitiger URL-Builder

Baue die iframe-URL serverseitig, um die Authentifizierung zu zentralisieren und Credentials nicht im Client zu exponieren.

Node/Express Beispiel

app.get("/embed/article", (req, res) => {
  const token = req.query.token;
  const { manufacturer, program, basearticlenumber, ocdreinit, permanentid } = req.query;

  const params = new URLSearchParams({
    token,
    showprice: "true",
    disablecatalogue: "true",
    lang: "de",
    langalt: "en"
  });

  if (permanentid) {
    params.set("permanentid", permanentid);
  } else {
    params.set("manufacturer", manufacturer);
    params.set("program", program);
    params.set("basearticlenumber", basearticlenumber);
    if (ocdreinit) params.set("ocdreinit", ocdreinit);
  }

  const src = `https://web.3doffice.de/webkatalog2_5/planning?${params.toString()}`;
  res.send(`<iframe width="100%" height="800" style="border:0" src="${src}"></iframe>`);
});

Angular Beispiel

typescript

const base = "https://web.3doffice.de/webkatalog2_5/planning";
const params = new URLSearchParams({
  token: sessionToken,
  showprice: "true",
  disablecatalogue: "false",
  opencatalogue: "true",
  parentnode: "_ROOT::DX::WEBTI",
  lang: "de",
  langalt: "en"
});
window.location.href = `${base}?${params.toString()}`;

PermanentID-Generierung

Um eine permanentid für die Wiederherstellung einer Artikelkonfiguration zu generieren, sende das vollständige Top-Level-Artikel-JSON per POST an ofml.dll/ofml/reinit. Die zurückgegebene ID kann für spätere Planning-URL-Einbettungen gespeichert werden.

cURL Beispiel

bash

curl -X POST "https://web.3doffice.de/webkatalog2/api/ofml.dll/ofml/reinit?token={TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"json":{"id":"{GUID}","rootid":"{GUID}","manufacturer":"_dx","program":"webti","basearticlenumber":"27R0614Q","children":[],"ocd":{"reinitstring":"eJ...::"}}}'

Hinweis

Die permanentid unterstützt vollständige Meta-Planungs-Rekonstruktion einschließlich aller Kinder und Eigenschaften. Im Gegensatz dazu stellt ocd/reinit nur einzelne Artikelkonfigurationen wieder her.

Warenkorb-Integration

Wenn urlwarenkorb angegeben wird, zeigt der WebKatalog eine Aktion zum POSTen des aktuellen Artikels an diese URL.

Empfänger-Beispiel (Node)

app.post("/warenkorb", express.json(), (req, res) => {
  const cartItem = req.body;
  res.json({ ok: true, id: cartItem?.json?.id });
});

POSTed-Payload (Auszug)

json

{
  "json": {
    "id": "{815F0BB3-0BC2-4D9B-AE21-0B25F026A14F}",
    "rootid": "{815F0BB3-0BC2-4D9B-AE21-0B25F026A14F}",
    "manufacturer": "_dx",
    "program": "webti",
    "basearticlenumber": "27R0614Q",
    "propclasses": [],
    "children": [],
    "ocd": {
      "finalarticlenumber": "27 R 06 14 KL Q",
      "price": 540,
      "currency": "EUR",
      "shorttext": "Rechtecktisch, Tiefe 600 mm, Breite 1400 mm",
      "varianttext": "Höhe: 720 mm - 1160 mm\nPlattenfarbe: Buche\n...",
      "reinitstring": "eJytkUEOgkA..."
    }
  }
}

Warenkorb-Regeln

Speichere immer den Top-Level-Artikel (id == rootid) mit vollständigem JSON-Payload
Verwende id/rootid-Semantik zum Gruppieren und Rekonfigurieren von Meta-Planungen
Versuche niemals, ein einzelnes Kind unabhängig von seinem Root zu rekonfigurieren

v1 → v2.5 Migration

Parameterumbenennung

v1 Parameter	v2.5 Parameter
`manuid`	`manufacturer`
`seriesid`	`program`
`baseartnmbr`	`basearticlenumber`
`finalartnmbr`	`finalarticlenumber`
`reinitstring`	`ocdreinit` (visuell)

URL-Einstiegspunkte

v1	v2.5
`index.php`	`/planning`
`configurator.php`	`/planning`
`article.php`	`/planning`

Server-Adapter für Legacy-Links

function migrateV1ParamsToV25(q) {
  const p = { ...q };
  if (p.manuid) p.manufacturer = p.manuid, delete p.manuid;
  if (p.seriesid) p.program = p.seriesid, delete p.seriesid;
  if (p.baseartnmbr) p.basearticlenumber = p.baseartnmbr, delete p.baseartnmbr;
  if (p.finalartnmbr) p.finalarticlenumber = p.finalartnmbr, delete p.finalartnmbr;
  if (p.reinitstring) p.ocdreinit = p.reinitstring, delete p.reinitstring;
  return p;
}

Warenkorb-Handling

v1	v2.5
Speichert manuid/seriesid/baseartnmbr/reinitstring	Speichert vollständiges Top-Level-JSON mit id/rootid und ocd-Daten
Rekonfiguration einzelner Artikel	Rekonfiguration nur über Meta-Root (id == rootid)

v2 → v2.5 Migration

Wichtige Änderungen

Frontend-URL: Die visuelle Oberfläche wechselt von webkatalog2 zu webkatalog2_5. Die API bleibt unter webkatalog2.
Kompatibilität: Bestehende v2-URLs funktionieren nach Anpassung des Basis-Pfads weiterhin.
Best Practice: permanentid für Meta-Restores in Embeds bevorzugen statt nur ocdreinit.

Planungs-Einstiegspunkt

Der /planning-Endpunkt ist der einheitliche Einstieg für Konfigurator- und Katalog-Modi.

https://web.3doffice.de/webkatalog2_5/planning?[parameters]

Modus	Parameter	Beschreibung
Katalog	`opencatalogue=true`	Katalog anzeigen, optional mit `parentnode`
Konfigurator	`disablecatalogue=true`	Fokussierte Konfiguration eines Artikels
Hybrid	Keine der beiden	Katalog und Konfigurator gemeinsam

Bilder & Grafik (veralteter Service)

Veraltet

Die ODB-Bild-Generierung gilt als veraltet und könnte in zukünftigen Versionen entfernt werden. Bevorzugt wird die clientseitige Bildgenerierung. Die Endpunkte bleiben für spezielle Use-Cases (z.B. ERP-Integration) verfügbar.

articlesimage.jpg

https://web.3doffice.de/webkatalog2/api/odb.dll/odb/articlesimage.jpg?token={TOKEN}&manufacturer=_D&program=WEBTI&basearticlenumber=27R0614Q&finalarticlenumber=27%20R%2006%2014%20KL%20Q&reinitstring=eJ...

btg

https://web.3doffice.de/webkatalog2/api/odb.dll/odb/btg?token={TOKEN}&manufacturer=_D&program=WEBTI&basearticlenumber=27R0614Q&finalarticlenumber=27%20R%2006%2014%20KL%20Q&reinitstring=eJ...

Bekannte Einschränkungen

Nur Meta-Root rekonfigurieren: Rekonfiguriere ausschließlich den Meta-Root (id == rootid), niemals ein Kind unabhängig
Bilder für Meta-Planungen: articlesimage.jpg unterstützt keine zusammengesetzten Meta-Bilder — plane UI-Vorschauen entsprechend und nutze OCD-Renders oder andere Techniken
PermanentIDs nicht portabel: PermanentIDs sind nicht zwischen Test- und Produktivsystem übertragbar

Migration & Integration Guide ​

Zusammenfassung ​

Basis-URLs ​

iFrame-Einbindung ​

Standard-Artikel-Ansicht ​

Spezifische Konfiguration (OCD-only) ​

Volle Meta-Planung (permanentid) ​

Serverseitiger URL-Builder ​

Node/Express Beispiel ​

Angular Beispiel ​

PermanentID-Generierung ​

cURL Beispiel ​

Warenkorb-Integration ​

Empfänger-Beispiel (Node) ​

POSTed-Payload (Auszug) ​

v1 → v2.5 Migration ​

Parameterumbenennung ​

URL-Einstiegspunkte ​

Server-Adapter für Legacy-Links ​

Warenkorb-Handling ​

v2 → v2.5 Migration ​

Wichtige Änderungen ​

Planungs-Einstiegspunkt ​

Bilder & Grafik (veralteter Service) ​

articlesimage.jpg ​

btg ​

Bekannte Einschränkungen ​

Migration & Integration Guide

Zusammenfassung

Basis-URLs

iFrame-Einbindung

Standard-Artikel-Ansicht

Spezifische Konfiguration (OCD-only)

Volle Meta-Planung (permanentid)

Serverseitiger URL-Builder

Node/Express Beispiel

Angular Beispiel

PermanentID-Generierung

cURL Beispiel

Warenkorb-Integration

Empfänger-Beispiel (Node)

POSTed-Payload (Auszug)

v1 → v2.5 Migration

Parameterumbenennung

URL-Einstiegspunkte

Server-Adapter für Legacy-Links

Warenkorb-Handling

v2 → v2.5 Migration

Wichtige Änderungen

Planungs-Einstiegspunkt

Bilder & Grafik (veralteter Service)

articlesimage.jpg

btg

Bekannte Einschränkungen