Running a webshop connection

Before you start

Six things, and the first two are the ones that take calendar time rather than work. Start them before you plan anything else.

• A pCon.ui instance of your own from EasternGraphics or your distributor, set up as a shop instance. One licence is enough for both the configurator and the catalogue import: the import runs on the same instance id with a _wcf suffix, and that variant comes with the pCon.ui licence. An instance is either a shop instance that ends in add to cart or a lead instance that ends in a request form, never both, and only EasternGraphics can switch it
• Your domains on the whitelist at EasternGraphics. One live plus two development, no wildcards, every subdomain separately, and it is done by hand on request
• Manufacturers who publish OFML data and have shared their catalogue with your account. If this is not true for a brand, nothing in this manual will make it work for that brand
• A shop on a platform we have an adapter for, and an administrator account on it that can install an extension
• A key from your portal, issued for the site it will run on. Issue a separate one per environment instead of copying a live key into staging
• Room in PHP for a big configuration. max_input_vars defaults to 1000, which runs out at roughly twenty articles in one configuration, so ask your host for 5000 and a post_max_size to match. Below that the shop refuses a large configuration instead of accepting half of it

The order of operations

The sequence matters, because two steps wait on other people and the rest does not. Get the waiting started on day one.

1. Ask EasternGraphics for the whitelist entries. Decide which three domains first. This is the step most likely to add a week, so it goes first even though it is needed last.

2. Set your configurator instance in the portal. The portal validates the id against EasternGraphics and shows you what is actually on your domain list, so you can see whether step one has landed rather than asking.

3. Issue a key for the site. The raw key is shown exactly once. Store it where your shop's other credentials live, not in a chat message.

4. Install the adapter and paste the key. The connection registers itself the first time it calls, and from then on it appears in your portal with the version it is running.

5. Import a handful of articles, not the catalogue. Pick one simple article and one complicated one. You are checking language, price and whether the specification arrived, and you want to find that out on two products rather than two hundred.

6. Open the configurator on one of them. If step one has not landed yet, this is where you will notice.

7. Configure something and add it to the cart. Check the price, the specification and the component articles on the cart line, then place a test order and check the same on the order.

8. Then import the rest, and only then.

The catalogue import

The import runs from your shop's server to ours and from there to the catalogue. You browse the real manufacturer tree inside your own admin, tick what you want, and create products from it.

What it writes per article:

• The title, either from the manufacturer's own text or from a template you set
• The specification as a table of properties and values
• The price for the starting configuration
• The render as the product image
• Brand and series, as something you can filter on
• The article reference, which is what lets the product page build its own configurator later

What it skips. Articles the manufacturer marks as not orderable are not imported, and the reason appears in the error list rather than silently. An article that comes back without any usable text is a symptom, not a skip: see the language note below.

What a re-import does. Running it again follows the new price list and the new texts. The image gallery is replaced rather than appended, so repeated imports do not pile up renders, and an article whose image and render are the same file is stored once instead of twice.

One article is not one product. An article number encodes a starting configuration, not a model. A desk article may carry a choice list of ten widths, which means importing every article number in a series can produce thirty products where one would do. Decide how you want a series modelled before you import it, because undoing it afterwards is tedious.

The configurator on the product page

The configurator loads in an iframe on your own product page, on your own domain, with your catalogue and your prices. There is no separate configurator site and no second checkout.

The address it loads is composed when the page renders, out of two things: the article reference stored on the product, and the configurator instance held centrally for your account. Nothing is baked into the product record. That is not a detail: it means moving to a different pCon instance is one edit in one screen, instead of touching every product you ever imported.

A per-product manual address exists as an override, for the cases where a product needs something the automatic composition cannot express. Treat it as an escape hatch. A product with a manual address stops following your central settings, and that is easy to forget a year later.

Settings, and which layer wins

The appearance parameters of the configurator come from four layers, each overriding the one before it. Knowing the order is the difference between changing a setting and wondering why nothing happened.

1. What the adapter derives. The interface language and the product data language come from the locale of the page; the tax country comes from your shop's own tax configuration. For most shops this is already right and you never touch the other three layers.

2. Your tenant profile in the portal. The fleet default, for a customer running more than one shop.

3. The connection profile in the portal. The per-shop answer, and the layer you most likely want. These parameters describe how the configurator is embedded, which is a property of the shop rather than of the licence.

4. The store view or the shortcode. The escape hatch, for one store view or one page that genuinely differs.

The adapters deliberately hold no appearance settings of their own beyond the overrides above. They used to, and a setting with a default always wins over a central value, which meant the central profile could never actually reach a shop. If you are looking for where to change something, start at layer three.

Two languages, not one. The interface language sets the buttons and the chrome. The product data language sets the manufacturer's own property and material names. They are separate settings and they are allowed to differ, but if you set them to different values by accident your configurator will show English buttons over Dutch materials, or the reverse.

From configuration to order line

When the customer presses add to cart, the configurator posts the result to a signed address on your own shop. Your shop verifies the request before anything touches the cart, imports the render, and sends the visitor to the cart.

The transport is OCI punchout, the same industry standard used between procurement systems and supplier catalogues. That is deliberate: it is a format your platform's developers may already know, and it is not something we invented for this.

What a configured line carries:

• The title and the manufacturer article number, both following the configuration rather than the product it started from
• The configured price, with net and gross kept apart
• The variant code and the manufacturer and series codes
• The readable feature text: every property the customer chose
• The component articles underneath the line, each with their own number and price, so purchasing can order against them
• The render
• A link that reopens the exact configuration, valid for 24 hours

Verified prices. The configurator signs the price it reports, and your shop can verify that signature before accepting it. Without that check, a price posted to your shop is a claim rather than a fact, and a desk of ten thousand euros can be added to a cart for one. The setting is called Require verified prices and it ships on. Leave it on. The one case for switching it off is an instance that carries no prices at all: it then sends no signature, so every add to cart would be refused.

Reconfiguring. The reopen link brings back exactly what the customer configured. It expires after 24 hours, which is long enough for a customer to finish a session and short enough that an old link in an email does not become a way back into a stale price.

WooCommerce specifics

A normal WordPress plugin with no build step. Settings live under the plugin's own screen and are grouped the way this manual is: connector, configurator, configure button, product import, security.

Where the configurator goes on the page. WooCommerce themes differ wildly, so placement is a setting rather than an assumption: before the product summary, after it, inside it, after the whole product, or manual only. There is a placement priority next to it for themes that need the hook to run earlier or later than usual. If your theme fights you, set placement to manual and drop the shortcode where you want it.

Useful neighbours. The iframe height takes any CSS length, so70vh and 800px are both fine. There is an option to use the pCon iframe resizer, and one to hide the theme's own product summary for products that are fully configured through the iframe.

Import options. You choose per field whether the import writes the title, description, price, images, attributes, brand and series, and the SKU. Title can come from the manufacturer's long text or short description, or from a template you write. Switch off whatever your shop maintains by hand, and a re-import will leave it alone.

Magento 2 specifics

A Magento 2 module installed with Composer from a private repository of ours, as bewise/module-pcon-configurator. It needs Magento 2.4 or newer on PHP 8.3, 8.4, 8.5, which is what the package declares for itself, so Composer checks it before installing rather than leaving you to find out.

Where everything is. Settings sit under Stores, Configuration, in a BEWISE section, behind their own permission so you can hand catalogue work to someone without handing over the key. The catalogue browser is its own admin page under Catalog.

What it does to your catalogue. The article reference and the manual override are product attributes added through data patches. Every pCon feature becomes a filterable select attribute, which means layered navigation works on the configuration options themselves rather than only on your own attributes. Brand and series become categories, because Magento has no brand taxonomy to put them in.

Scope. The import writes in default scope, so imported data appears in the admin form and applies to every store view at once. Per store view differences belong in the override layer, not in the import.

After any change to the module, clear the caches. Magento compiles dependency injection and generated code, and it will keep running the compiled version of the old code without telling you. This is ordinary Magento behaviour and not specific to this module, but it is the single most common reason a change appears to have done nothing.

What you can change without us

Everything in the portal and everything in the adapter's settings screen, which between them covers almost all of day to day operation:

• Your configurator instance, validated against EasternGraphics when you save it
• Languages, tax country and the other embedding parameters, per shop
• Issuing and revoking keys, with both actions recorded
• Which fields the import writes, and how titles are built
• Where the configurator sits on the page, and how tall it is
• Whether unverified prices are accepted

What you cannot do yourself is add a domain to the whitelist, because that is EasternGraphics' list and not ours, and create your own portal account, because accounts are created by us. Everything else is a screen.