Migration & Integration Guide

This guide describes the migration from WebKatalog v1 to v2(.5) as well as optimizations for existing v2 integrations.

Summary

• Build a planning URL with a valid token and either a base article (manufacturer/program/basearticlenumber) with an optional ocdreinit, or a permanentid
• Embed this URL as the iframe src in the customer website or web shop
• Migrating from v1: use the /planning entry point, rename the parameters, and store the complete article JSON in your shopping cart instead of the individual article fields (see Shopping cart handling)
• Migrating from v2 → v2.5: mostly compatible; adjust the frontend base URL and prefer permanentid flows

---

Base URLs

Test and production URLs: see URLs & Environments.

---

iFrame embedding

The recommended approach: build the planning URL on the server with a valid token and the desired parameters, and use it as the iframe src.

Standard article view

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

Specific configuration (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>

Full meta planning (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>

---

Server-side URL builder

Build the iframe URL on the server to centralize authentication and keep credentials out of the client.

Node/Express example

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 generation

To create a permanentid, POST the complete top-level article JSON to ofml.dll/ofml/permalink. The response contains the ID in the id field; store it for later planning URL embeds.

cURL example

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

The body in the example is abbreviated. Send the complete article JSON from GET /articles or CURRENT_ARTICLE. An incomplete body is also answered with an id, but that ID can't be loaded.

Note

The permanentid supports full reconstruction of the meta planning, including all children and properties. By contrast, ocdreinit only restores single article configurations.

---

Shopping cart integration

See Shopping cart integration.

---

v1 → v2.5 migration

Parameter renaming

v1 parameter	v2.5 parameter
manuid	manufacturer
seriesid	program
baseartnmbr	basearticlenumber
finalartnmbr	finalarticlenumber (REST API only, e.g. /btg; the planning URL doesn't need it)
reinitstring	ocdreinit (visual)

URL entry points

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

Server adapter for 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;
}

Shopping cart handling

v1	v2.5
Stores manuid/seriesid/baseartnmbr/reinitstring	Stores the complete top-level JSON with id/rootid and ocd data
Reconfiguration of single articles	Reconfiguration only via the meta root (id == rootid)

---

v2 → v2.5 migration

Key changes

• Frontend URL: The visual interface moves from webkatalog2 to webkatalog2_5. The API stays under webkatalog2.
• Compatibility: Existing v2 URLs keep working once the base path is adjusted.
• Best practice: Prefer permanentid for meta restores in embeds instead of ocdreinit alone.

---

Planning entry point

The /planning endpoint is the single entry point for configurator and catalog modes.

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

Mode	Parameter	Description
Catalog	opencatalogue=true	The catalog is open on start, optionally with parentnode
Configurator	disablecatalogue=true	No catalog; only the loaded article
Hybrid	Neither of the two	The catalog is closed and can be opened with the catalog button

---

Images & graphics

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

---

Known limitations

• Reconfigure the meta root only: Reconfigure only the meta root (id == rootid), never a child on its own
• Images for meta plannings: articlesimage.jpg does not support composite meta images — plan UI previews accordingly and use OCD renders or other techniques
• PermanentIDs are not portable: PermanentIDs cannot be transferred between the test and production systems