Building against Manufacturing PLM

Three surfaces, and choosing between them

There are three ways to write software against Manufacturing PLM, and picking the wrong one is the most common early mistake. It is not usually fatal, but it is expensive to undo once something is in production.

• The REST API is for reading and writing on demand, from your own systems, under a specific identity. Reach for it when your code initiates the interaction — a portal that shows product data, a script that creates items from a supplier feed, a report your team runs.
• Webhooks are for reacting to what happens here. Reach for them when Manufacturing PLM initiates the interaction and your system needs to know: a revision released, a change approved, a publication failed. Polling the API on a timer to detect these is the anti-pattern webhooks exist to remove.
• The connector SDK is for integrations that own a seam — bidirectional, stateful, and reconciling. It exists because integrations of that kind need lifecycle, retry, idempotency and drift detection, and every team that builds those on raw API calls builds them slightly wrong.

The four invariants

Everything you build against inherits four properties. They are not configurable and they are not bypassable by any surface, which is worth knowing before you design around them.

Every write has an attributed actor. There is no anonymous write path, no service account that writes as nobody, and no way to make a change that the audit trail cannot attribute. An integration writes as an identity, and that identity appears on the record. This surprises people building automation, who expect the automation to be invisible. It is deliberately not.

Permissions are enforced at the data layer. An API token cannot see more than its identity may see, and this is checked below the API rather than in it — so there is no endpoint, no query parameter and no admin flag that widens it. If your integration needs broader access, it needs a broader identity, granted deliberately.

Structural reads are resolutions. When you read a bill of materials, you receive a resolution under stated conditions, with the conditions attached. You do not receive raw lines to evaluate yourself, because evaluating them yourself means reimplementing effectivity and variant logic in your own code, differently, and getting a different answer from the one the interface shows.

Released objects are immutable. A released revision does not change. Correcting something means a new revision through change control, and an API that let you edit a released object would be an API that made the audit trail a work of fiction.

Idempotency, and why it is not optional

Any write endpoint accepts an idempotency key, and any integration that does not send one will eventually create duplicates. This is not a hypothetical — it is what happens the first time a network timeout occurs after the server committed and before your client saw the response.

The failure is quiet and it compounds. A retried item creation produces two items with different identifiers describing the same physical part, which is the single most damaging data condition a PLM can hold: both records are individually correct, no validation fires, and every structural query afterwards returns half the truth.

So send a key derived from something stable in your own system — the source record's identifier, not a timestamp and not a random value generated at call time, because a retry must produce the same key as the original attempt or it accomplishes nothing.

The same discipline applies to webhook consumption in reverse. Webhooks deliver at least once, so your handler must tolerate seeing the same event twice. Every delivery carries an event identifier for exactly this purpose, and a handler that ignores it will double-process something on the first redelivery.

Reading structures without getting it wrong

The most common integration defect is not a bug in anybody's code. It is a structural read that asked a question slightly different from the one the developer thought they were asking.

A bill of materials has no single answer. It has an answer *as of a date*, *for a configuration*, *at a revision*, and those parameters are not optional decorations — omitting them means accepting a default, and the default is rarely the one a downstream system wanted.

So structural endpoints require the conditions explicitly rather than defaulting silently. An unparameterised request is refused with a message naming what is missing. It is a small friction that removes an entire category of *the numbers do not match* investigations, most of which end in the discovery that one system asked for today and the other asked for the release date.

The response carries the conditions it was resolved under, so a value stored downstream can always be traced back to the question that produced it. If you store a resolved structure, store the conditions alongside it — a stored resolution without its conditions is a number nobody can reproduce, and reproducing it is what somebody will need to do in eighteen months.

Webhooks in practice

Webhook payloads are deliberately thin: what happened, to which object, when, and by whom. They do not carry the object's full state, and that is not a limitation to work around.

A fat payload is a snapshot that is already stale when it arrives, and worse, it is a permission decision made at send time rather than at read time. A thin event tells your system something happened; your system then reads the current state under its own identity, which is both more correct and more secure.

Deliveries are signed, retried with backoff, and observable — you can see what was sent, what responded and what is queued. Endpoints that fail persistently are disabled rather than retried indefinitely, and disabling raises a task rather than happening silently, because a webhook endpoint that stopped receiving events without anybody noticing is the beginning of a long divergence between two systems.

Order is not guaranteed across objects. Events for a single object arrive in order; events for different objects may not. Building a state machine that assumes global ordering works in testing and fails under load, which is the worst time to discover it.

When to reach for the connector SDK

If your integration writes in both directions and needs to stay consistent, you want the SDK rather than the raw API. The distinction is not about complexity — it is about whether anybody is responsible for the two sides agreeing over time.

A one-way read is fine over the API. A nightly export is fine over the API. But a two-way seam accumulates state: what was published, when, whether it landed, whether it has since drifted, what to do when it has. The SDK provides that state and a reconciliation model over it, so that drift is a detected condition with a task attached rather than a surprise somebody finds during a stock count.

It also provides the operational surface. A connector reports its runs, its failures and its lag in the same place every other connector does, which means an administrator can answer whether an integration is healthy without reading your logs.

The rule of thumb: if you would need to build a reconciliation report to trust your own integration, use the SDK, because that report already exists in it.