Migration & Integration Guide

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

Zusammenfassung

• Erstellen Sie eine Planning-URL mit gültigem Token und entweder einem Basis-Artikel (manufacturer/program/basearticlenumber) mit optionalem ocdreinit oder einer permanentid
• Betten Sie diese URL als iframe-src in die Kundenwebsite oder den Webshop ein
• Migration von v1: den Einstiegspunkt /planning verwenden, die Parameter umbenennen und im Warenkorb das vollständige Artikel-JSON speichern statt der einzelnen Artikelfelder (siehe Warenkorb-Handling)
• Migration von v2 → v2.5: Hauptsächlich kompatibel, Frontend-Basis-URL anpassen und permanentid-Flows bevorzugen

---

Basis-URLs

Test- und Produktiv-URLs: siehe URLs & Umgebungen.

---

iFrame-Einbindung

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

Standard-Artikel-Ansicht

<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)

<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)

<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

Bauen Sie 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>`);
});

---

PermanentID-Generierung

Um eine permanentid zu erzeugen, senden Sie das vollständige Top-Level-Artikel-JSON per POST an ofml.dll/ofml/permalink. Die Antwort enthält die ID im Feld id; speichern Sie sie für spätere Planning-URL-Einbettungen.

cURL Beispiel

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

WARNING

Der Body im Beispiel ist gekürzt. Senden Sie das vollständige Artikel-JSON aus GET /articles bzw. CURRENT_ARTICLE. Ein unvollständiger Body wird ebenfalls mit einer id beantwortet, diese ID lässt sich aber nicht laden.

Hinweis

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

---

Warenkorb-Integration

Siehe Warenkorb-Integration.

---

v1 → v2.5 Migration

Parameterumbenennung

v1 Parameter	v2.5 Parameter
manuid	manufacturer
seriesid	program
baseartnmbr	basearticlenumber
finalartnmbr	finalarticlenumber (nur REST-API, z. B. /btg; die Planning-URL benötigt ihn nicht)
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 ist beim Start geöffnet, optional mit parentnode
Konfigurator	disablecatalogue=true	Kein Katalog; nur der geladene Artikel
Hybrid	Keine der beiden	Katalog ist geschlossen und über den Katalog-Button zu öffnen

---

Bilder & Grafik

articlesimage.jpg

https://web.3doffice.de/webkatalog2/api/odb.dll/odb/articlesimage.jpg?token={TOKEN}&manufacturer=_dx&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=_dx&program=webti&basearticlenumber=27R0614Q&finalarticlenumber=27%20R%2006%2014%20KL%20Q&reinitstring=eJ...

---

Bekannte Einschränkungen

• Nur Meta-Root rekonfigurieren: Rekonfigurieren Sie 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 — planen Sie UI-Vorschauen entsprechend und nutzen Sie OCD-Renders oder andere Techniken
• PermanentIDs nicht portabel: PermanentIDs sind nicht zwischen Test- und Produktivsystem übertragbar