The UnoPim connector
The whole UnoPim route: what has to exist in the PIM, how the connection is configured, what the first sync publishes, and where the data surfaces in DDM and on the published passport page.
Two halves, one installed
The UnoPim route has two halves, and it helps to keep them apart from the start. The connector is a service of ours that reads UnoPim over its REST API, maps what it finds onto GS1 terms, publishes the result into the catalog and writes a short answer back. It needs nothing installed inside the PIM. The optional PHP package puts a panel above the product form, where the person editing a product can see what the platform currently says about it, draw a number, or enter one they already have.
Because the data half installs nothing, nothing in a customer's PIM has to be kept in step with our repository. Its entire footprint is an OAuth client, one api_keys row, a handful of attributes and one webhook. The connector only speaks the published REST API, so an upgrade on our side never needs a deployment window in someone else's system.
Everything below is verified against UnoPim 3.0.0.
What UnoPim needs
Start from the products themselves. UnoPim holds them the way a PIM does: a SKU, an attribute family, values in up to four sections (common, locale_specific, channel_specific and channel_locale_specific) and media files in its own storage. The connector reads all four sections and lets the most specific value win, in this order: channel and locale, then channel, then locale, then common.
An API client
The REST API uses OAuth2 with the password grant (Laravel Passport). Create the client in the admin UI under Integrations → API Keys, because that route creates the OAuth client together with the matching api_keys row in one step. The row matters more than it looks: ScopeMiddleware refuses any request whose admin has no row in api_keys and answers This action is unauthorized, even when the token itself is valid. Building the client by hand runs into three quirks of 3.0.0. The artisan command creates the client and then fails before printing its credentials, client secrets are stored hashed so a plaintext secret answers Client authentication failed, and grant_types is already cast to an array, so writing JSON into it double-encodes the value.
A handful of attributes
UnoPim's own passport preset (php artisan unopim:passport:install-preset) creates the passport template and its fields, leaves every field unsourced and creates no attributes. The GTIN attribute is therefore yours to make: create dpp_gtin as a text attribute, add it to the families in use, and point the template's GTIN field at it. For lot-level records the same preset names dpp_batch_identifier (role Batch), which the connector reads as the batch qualifier; source.options.batch-from points it at another attribute.
Two more attributes cover information UnoPim has no field for, and the connector reads both as input: ddm_gpc_code carries the GS1 product classification and ddm_target_market the market a product is destined for. A third, ddm_action_required, is written by the connector and described further down. All our attributes share the ddm_ prefix so they never collide with UnoPim's own dpp_* preset codes, and removing the connector means deleting the ddm_ attributes and nothing else.
One webhook
Under Settings → Webhooks, subscribe to product.created and product.updated and point them at:
https://<connectors-host>/webhooks/unopim/<connection-name>
Set the same secret you configure as source.webhook-secret. UnoPim signs with X-Unopim-Signature: sha256=<hex>, an HMAC-SHA256 over the raw body. The connector verifies that signature before it does anything else and answers an unsigned or wrongly signed call with 401.
The webhook serves as a doorbell. The connector takes the SKU from its payload and fetches the record fresh from the API, and it never reads the payload as data. Measurements against 3.0.0 show why: a create delivers twice (product.created and product.updated, with identical bodies), a failed delivery is never retried, and on a create the payload does not even carry the dpp_gtin set in the same request. Ringing twice costs nothing, since publishing is idempotent.
The connection on our side
A connection is a block of configuration naming one UnoPim and one catalog:
openepcis.connectors.connections.pim1.source.type=unopim
openepcis.connectors.connections.pim1.source.url=https://pim.example.test/api/v1/rest
openepcis.connectors.connections.pim1.source.auth.kind=oauth2-password
openepcis.connectors.connections.pim1.source.auth.key=<oauth client id>
openepcis.connectors.connections.pim1.source.auth.secret=<oauth client secret>
openepcis.connectors.connections.pim1.source.auth.username=<admin email>
openepcis.connectors.connections.pim1.source.auth.password=<admin password>
openepcis.connectors.connections.pim1.source.webhook-secret=<shared secret>
openepcis.connectors.connections.pim1.target.resolver-url=https://id.example.test
openepcis.connectors.connections.pim1.target.gcp-prefixes=9521234
openepcis.connectors.connections.pim1.target.access-level=Public
openepcis.connectors.connections.pim1.target.default-net-content=1 H87
These keys are the whole configuration surface. They are read as ordinary Quarkus properties, and there is no configuration file of our own. In a cluster the same keys arrive as environment variables: the property name in upper case, with every non-alphanumeric character turned into _, so …pim1.target.offline-token becomes OPENEPCIS_CONNECTORS_CONNECTIONS_PIM1_TARGET_OFFLINE_TOKEN. The keys that carry secrets (the OAuth secret, the admin password, the webhook secret, the offline token) belong in a Kubernetes secret mounted into the deployment; the block above only names them. How to issue the offline token, why it has to be an offline token, and what revoking it does to a running connection is covered in Integration Tokens.
source.url is the REST base path. The token endpoint is derived from the origin (/oauth/token) and only needs configuring if a deployment moves it. Two optional settings, source.options.locale and source.options.channel, decide which scope a single value is read from. Leaving them out reads common values only, which is the safe default, because choosing a locale on the tenant's behalf would publish a value nobody asked for. Translations are collected regardless of these settings, as the section on the language map below explains.
Two of the target settings deserve a sentence each. access-level is the publication tier. Resolution answers an anonymous reader with 404 No records found until a record is Public, so a passport meant for a consumer's phone has to be published at that level. default-net-content is the quantity a record states when the source states none, written as "<value> <unit code>" and usually 1 H87, one piece. GS1 Germany rejects a product registration without a net content, and an indivisible article has nothing to measure. Where the source does give a quantity, such as 250 g of coffee, the source value wins.
Where the identifier lives
UnoPim knows nothing about GS1. It knows a SKU, which is a unique record key, and the connector decides per connection what role that SKU plays:
openepcis.connectors.connections.pim1.source.options.gtin-from=composed # the default
openepcis.connectors.connections.pim1.source.options.gtin-from=sku
openepcis.connectors.connections.pim1.source.options.gtin-from=dpp_gtin
Each mode fits one situation:
composed: the SKU carries the article reference. Everything up to the first hyphen (the whole SKU where there is none) is left-padded with zeroes, joined to the company prefix fromtarget.gcp-prefixes, and completed with a computed check digit. Nothing is held twice, and since nobody types a check digit, nobody can mistype one.sku: the SKU already is the full GTIN. This is the case for merchandise that arrives with someone else's EAN, where the prefix in the key belongs to another company and composing would produce a wrong key.- an attribute code, usually
dpp_gtin: the key lives in a field of its own. Use this mode for non-numeric SKUs and for keys that come from elsewhere.
A tenant licensed for several prefixes is a normal situation, and it rules out composing, because the connector would have to guess which prefix an article belongs to. composed therefore refuses outright as soon as a connection lists more than one prefix. The key then has to come from a field: the SKU where it already is the full GTIN, or an attribute that holds it.
The hyphen is what lets batch records live as ordinary products in the PIM. 95201 and 95201-L240815 compose to the same key, 9521234952015, so a batch shares its model's GTIN and the suffix only satisfies UnoPim's requirement that every SKU be unique. The batch number itself comes from an attribute, dpp_batch_identifier unless source.options.batch-from names another. The connector publishes such a record one level down, at the instance path, and skips it as a model record so that batch data never overwrites the model's. In sku mode and in attribute mode nothing is split at a hyphen, and the value is taken as the key exactly as it stands. The hyphen rule belongs to the UnoPim connector alone; the other connectors read their key from the source.
Every refusal is logged by name. A missing prefix, a non-numeric article reference or a reference too long to fit each produces a log entry, and the record is skipped, so no key is ever produced that points at somebody else's product.
The first sync
Leave dry-run at its factory value of true for the first pass. Arming a connection is an explicit act, because real registries sit downstream of the catalog, GS1 production among them. Before that first pass, ask the diagnosis ladder what already works:
curl https://<connectors-host>/connections/pim1/diagnostics
It reports the platform token, an authenticated catalog read, the tenant claim on the catalog, source reachability, the webhook configuration and, where the connection has it enabled, EPCIS capture as separate rungs, so a failure tells you which of them broke. Then run one poll with dry-run=true and read the log, which prints exactly what the connector would have published.
The poll pages through /products a hundred at a time, filtered on updated_at, and keeps a running maximum as its cursor. Unchanged records are recognised by a canonical SHA-256 hash of the payload and are not written again. The stamp is kept in a declared control field on the catalog record, connectorStamps, keyed by connection name, so several connections can stamp the same record without erasing each other. A nightly full sweep runs on top of the delta poll and does the actual reconciliation; the webhook only makes changes arrive sooner.
The default mapping
A mapping is data: one YAML file per connection, with unopim-default.yaml as the file every connection starts from. Most installations only ever add to it, so it is worth knowing what it already carries.
UnoPim's name becomes productName. Short and long text stay apart. short_description becomes productDescription, the one-line description a consumer app shows under the name, and the long copy in description becomes productMarketingMessage, which the vocabulary defines as the consumer-friendly detailed description. Neither maps to additionalProductDescription, because in the GS1 vocabulary that term describes variants such as style, colour or fragrance, however plausible it reads. UnoPim stores both texts as HTML and the GS1 terms are plain strings, so the adapter strips the markup before publishing: block elements become blank lines, list items become bullets, and entities are resolved.
Images travel as referenced files. UnoPim reports a storage path; the adapter turns each path into a public URL and builds an entry of the form { "referencedFileType": "PRODUCT_IMAGE", "referencedFileURL": … }, and the list of these entries lands on referencedFile. The rule runs in one direction only, and nothing writes images back into the PIM.
Translations keep all their languages. Every locale-scoped value the PIM already holds is published as a GS1 language map, keyed by the bare language, so de_DE becomes de. Where two locales share a language, as de_DE and de_AT do, the connection's own locale wins, because that is the one the operator chose.
The adapter builds these language maps whether or not a locale is configured, collecting a product's locale-scoped sections into one map per attribute. The translations are already maintained, and a passport that cannot answer in the reader's language is the first thing a consumer notices. The configured locale only decides which language wins a collision and whether locale-specific values are also taken over as flat values.
Values UnoPim holds as common behave differently. They arrive as a single text without a language, so a localized rule over such a value needs source.options.locale. Without it the connector fails that one record with an error that names the rule and the setting, so no text is ever filed under a blank language key. The run carries on with the other records.
Measurements are mapped without a unit in the rule. weight becomes netWeight (netContent means something else), and length, width and height become inPackageDepth, inPackageWidth and inPackageHeight. The unit comes from UnoPim's own measurement attribute, which carries a value such as {"unit":"GRAM","amount":"250.0000","symbol":"g"}. The adapter resolves it against the platform's UN/CEFACT Recommendation 20 table (721 units across 51 dimensions), first by symbol and then by code, and produces {"value":250,"unitCode":"GRM"}. If the unit cannot be determined with certainty, the whole value is withheld and the reason logged, because a number with a guessed unit does more harm than a missing one.
Where the PHP package is installed, the channel becomes the market. A channel is the axis along which UnoPim varies price, name and description, and the package lets a merchant state once per channel which countries that channel sells into. The adapter reads this back over the package's own /openepcis/channel-markets route and maps it onto targetMarket. Without the package the answer is simply empty, which is the ordinary case and makes no claim about where the product sells. If the product itself names a market in ddm_target_market, the product value wins and the channel value is held back.
Beyond that, the default mapping carries brand onto brand.brandName, color onto colourCode[].colourCodeValue, size onto sizeCode[].sizeCodeValue, ddm_gpc_code onto gpcCategoryCode, and a catalogue price where the owner has enabled price sync.
The mapping file contains no identifiers. The adapter reads the GTIN, the GLN and the batch identifier into the sync key, because they say which record this is, while the payload says what the record holds. The complete field table (source field, target term, direction, vocabulary, value shape and, taken from the ontology itself, what the target term means) is generated from the mapping file, so it always matches the rules that actually run.
The panel in UnoPim
The optional PHP package hooks into UnoPim's own unopim.admin.catalog.product.edit.form.before event and renders a panel above the product form. Identity is a property of the product someone is already editing, so the panel sits on that form and has no screen of its own.
With a GTIN present, the panel shows the key, the batch number when the record names one, and the identity status: green when the key is structurally sound, red with the platform's own wording when something needs fixing. It also shows the licensee GS1 names for the key, the company prefix (flagged as own prefix where it is yours), the canonical GS1 Digital Link as a clickable link, and a QR code rendered from it. The verdict is fetched on the server while the page renders, without any JavaScript in the browser, and almost none of it is stored, since a licensee name written into a product last month only tells you what was true last month.
Without a GTIN, the panel offers two equally weighted routes. Draw the next GTIN allocates the next article number from your own prefix through the platform. I have a GTIN takes a number the merchant already owns, has the platform check it, and refuses it in the platform's own words if it is wrong. Both are needed: a merchant who already holds a valid number can use it, and a merchant without one gets a properly allocated key and has no reason to invent one.
A draw takes far longer than a verdict. A verdict comes back in milliseconds, while the free-key pool is answered by sorting an entire base number, which was measured at around twelve seconds. Drawing therefore has its own timeout, ninety seconds by default, separate from the short one the panel uses for verdicts.
Both routes are plain form posts that reload the page, because the browser never executes a <script> injected through UnoPim's render event.
A second widget replaces the raw GPC field with a word search, so a category can be found by typing coffee without knowing the eight-digit brick code. In both widgets the browser holds no platform credential: the browser calls the package, and the package calls the bridge.
What comes back
By default the connector writes two fields back into UnoPim.
The first is the full key, written into dpp_gtin, which is UnoPim's own passport field for it, with role Gtin. A composed key exists nowhere a person can see it (the SKU has five digits, the key thirteen), and a merchant asked for a product's GTIN has to be able to read it. The write-back is offered on every tick, independent of a publication, and that is what restores a key somebody cleared in the PIM. The value is derived and written by us, and it is kept out of the product form so that nobody edits a value the next run will overwrite.
The second is ddm_action_required, yes or no. It is the one field a person acts on, and it answers the question whether something here is wrong and theirs to fix. It comes straight from the verdict's dataProblem flag, and the distinction that flag draws is the reason the whole connector exists.
A verdict carries much more than a yes or no: syntax and check digit, the prefix boundary, the registry status, the licensee, a reason, a canonical Digital Link, and the provenance of each individual statement. The provenance includes whether an answer came from the registry or from cache, and when the registry answered, which can differ from when we last looked.
Some of what a verdict says concerns the record, and some concerns our side. unverified means the GS1 registry could not be reached, and the merchant's number may be perfectly good. Writing that status into the product form would send people to retype correct data, which is exactly the failure this connector prevents. The identity status is therefore never written back, and the panel fetches it live.
Both values are patched only when the record does not already hold them, so a steady state costs no writes at all.
The mapping also states explicitly which system owns a field. Every rule declares a direction: to-catalog (the default; the source owns the field and is never written into), from-catalog (DDM owns it; it is written into the source and skipped when the outgoing document is built) or both. For both the more recent edit wins, and the connector decides this by comparing the publish stamp on the catalog record. Timestamps would not work here, since two systems have two clocks and two notions of modified, and a PIM that touches updated_at on every save would win every race whether anything changed or not.
Direction has to be declared. Inferred from the shape of a rule, it would make every ordinary rule bidirectional; both systems would then claim the same field, and on each tick the publish would overwrite the catalog edit the pull-back had just carried into the source, silently and without any error. Rules that cannot run backwards at all, such as a target that fans out or a rule with a fixed unit, are rejected when the file is read, with the rule named, because a wrong value written into somebody's PIM does more harm than none.
In DDM and on the passport page
In DDM, each published product appears as a master data record under its GTIN, carrying exactly the terms the mapping produced: names and descriptions as language maps, images as referenced files, measurements as typed quantities, the market and the classification. A record that names a batch is published one level down, at the instance path /01/<gtin>/10/<lot>, beneath its model. Serial numbers do not come from a PIM: UnoPim's passport has no role for them, and instances belong in the resolver and in EPCIS.
The last step joins the two systems by making UnoPim's own published passport page a target in the linkset. Three per-channel settings have to be switched on first: the passport feature itself (catalog.product_passport.settings.enabled), publication (general.publication.settings.enabled) and public access (general.publication.settings.public_access). Without the first, templates install cleanly and stay completely invisible; without the third, a publish is refused with 422. The template is attached to the attribute family, which is the least obvious point of the whole setup: until a family has a template, the readiness check reports missing_template.
One setting stays empty: general.publication.settings.base_url. UnoPim provides the product page, and the identity belongs to the resolver. The same setting also builds the address of the page itself, so pointing it at a resolver breaks more than the carrier: the JSON-LD then names a URL the resolver does not have.
Publishing is one call per SKU (POST /api/v1/rest/passports/publish/{sku}), after which the page lives at /p/{uuid}/{locale}, one version per language. Published versions are immutable, as a passport should be. A publish with unchanged content is refused, and a wrong version can only be withdrawn and never corrected.
The connector reads the published passports, takes the entries that are actually published, and registers the page on the record's anchor as gs1:pip. That link type stands for consumer information about the article and is kept apart from the passport itself. Two details are worth carrying with you. The link type must be written as a full IRI (https://ref.gs1.org/voc/pip), because a curie is no valid link type and the entry lands empty. And hreflang carries the bare language (de, en), because a regional subtag is accepted with 200 and the link is then discarded.
Withdrawal is the one direction the route does not follow. UnoPim can withdraw a published version, and while the connector only picks up entries that are currently published, it never removes a link it has already registered. An empty list of links is a no-op, so a withdrawn passport stays in the linkset as gs1:pip and points at a page that UnoPim answers with 200 and a tombstone.
The same holds one level up:
- A product deleted in the PIM simply stops appearing in the delta poll. A webhook for a SKU the API no longer knows is logged and the catalog document is kept, because a deletion in the catalog always takes an explicit act and never follows from a doorbell.
- A product merely deactivated in UnoPim keeps being published. Its status is carried into the payload and is never read as a publication decision.
Taking a record down is therefore a manual step today, done in DDM or against the catalog and linkset API.
The first sync does not yet give you an EN 18223 passport. That document is computed by a separate service, the DPP API, which derives it from the GS1 master data at the moment it is read.
The derivation has one mandatory field, economicOperatorId, which comes from the manufacturer organisation on the product record. UnoPim's gs1-product blueprint has no field for it, and it would be the same value on every article anyway, so the connection carries it: set target.economic-operator-gln to the GLN of your company, and the connector adds it as the manufacturer to every product that does not name one. Without it the derivation refuses the record and returns no passport at all, so a passport with a gap never goes out.
openepcis.connectors.connections.pim1.target.economic-operator-gln=9521234000006
The DPP API also has to read its master data from the resolver, which is not its built-in default.
The result is what a scan finally reaches. A code on the product resolves at the resolver, and the linkset offers the master data our catalog holds together with the product page UnoPim publishes. Even a serial number nobody ever recorded resolves, inherits the model's links and lands on the same page; that is the difference between a system that describes articles and one that tracks individual copies.
dry-run is on by default, and it matters: a connection publishes nothing until you write dry-run=false for it. Behind the catalog sit real registrars, GS1 production among them, and an allocated key cannot be taken back.