The Narravero connector
How the Narravero DPP Publisher and the OpenEPCIS catalog work together, what to set up on the Narravero side, where the GTIN comes from, how each passport gets a GS1 Digital Link on the brand's own domain, and what the connector writes back.
Narravero is a complete digital product passport platform. The DPP Publisher holds the templates and the design, the reader renders each passport on any phone, NFC tags and QR codes carry it to the product, and workflows and user roles govern who may change what. A brand that runs its passports there has done the hard part: the product data is structured, the templates are designed, and every item has a page.
The connector adds the GS1 layer on top of that work. It reads the records over Narravero's public v1 API, publishes each one to the OpenEPCIS catalog under a GS1 Digital Link on the brand's own domain, and registers the Narravero passport as the consumer destination behind that link. The same link then serves the GS1 master data document, an EN 18223 passport derived from it, and the EPCIS repository where visibility events about the item accumulate. Nothing is installed on the Narravero side.
Four things have to exist in the DPP Publisher before a connection can point at it: an API token, a view, the context ID, and the payload path under which this tenant keeps its GS1 key. The screens below walk through them in the order you meet them.
Every GTIN on this page is in the GS1 952 test range, and the resolver host in the screenshots is an example.org placeholder. The tenant is a demo workspace; the records were created over the same interface the connector reads from.
The context, and what a record is
A Narravero workspace is a context, and its ID is the first segment after /home/ in every Publisher URL. The connector needs it for the one request that lists everything in the workspace, so note it down from the address bar before anything else.
What Narravero stores is a Tridy: one identified thing, a unique ID, and a payload of "freely structured JSON", in the words of their own documentation. The payload is deliberately open, so a template can carry whatever a product group needs, and a DPP template reads it through placeholders such as ${gtin}.
Which keys a workspace uses is visible under Payload Key List. This tenant has three. Another tenant has different ones, and that flexibility is why the connector's default mapping is deliberately small and the GTIN path is configuration rather than a default.
The interface and the token
Records enter Narravero through an interface, created under Interfaces. An interface has a name the API addresses it by, points at a content type, and declares which payload path holds which identifier. The one below maps the payload key ean to the identifier type ean, which is the convention Narravero's own tutorial uses.
The connector reads interfaces to prove its credentials. GET /v1/interfaces needs a token and nothing else, no context, no view, no record, so a failure there is about the token and nothing else. That is the first rung of the diagnosis ladder for this source.
The API token is created on the second tab of the same page, API Tokens, with a display name and one click. It is sent as a bearer token and applies to the whole workspace. One detail matters when it goes into the connection: the static-token authentication kind sets the literal header value and adds no prefix, so the word Bearer belongs in the configuration.
openepcis.connectors.connections.brand1.source.type=narravero
openepcis.connectors.connections.brand1.source.url=https://api.narravero.com
openepcis.connectors.connections.brand1.source.auth.kind=static-token
openepcis.connectors.connections.brand1.source.auth.token=Bearer <the API token>
openepcis.connectors.connections.brand1.source.options.context-id=<context ID>
openepcis.connectors.connections.brand1.source.options.view-id=<view ID>
openepcis.connectors.connections.brand1.source.options.locale=de
openepcis.connectors.connections.brand1.target.resolver-url=https://id.example.org
openepcis.connectors.connections.brand1.target.gcp-prefixes=9521890
The token belongs in a Kubernetes secret, as every other credential here does; the block names the keys and is not the place for the values. Where the connection's own platform credential comes from is Integration Tokens.
Records, and where the GS1 key is checked
With the interface in place, records arrive over POST /v1/tridy/<interface name>. Three were created for this page: a shirt with a sound GTIN, the same shirt in another size with a transposed check digit, and a draft without any number yet.
[
{ "ean": "9521890340331", "productName": "Linen shirt, blue, M", "produktbezeichnung": "Leinenhemd, blau, M", "gtin": "9521890340331" },
{ "ean": "9521890340332", "productName": "Linen shirt, blue, L", "produktbezeichnung": "Leinenhemd, blau, L", "gtin": "9521890340332" },
{ "productName": "Draft: cotton tee, not yet numbered", "produktbezeichnung": "Entwurf: Baumwoll-T-Shirt" }
]
Narravero accepted all three, which is right for a passport platform: a draft is a legitimate record, and a GS1 key is one identifier among several a product can carry. The GS1 check lives in the connector, because the connector is the component that hands the key on to the resolver and to the registries behind it.
The connector reads each record's payload, fetches the identifiers the interface mapping filed for it, and merges them into the payload under ids, as ids.ean for the mapping in Figure 4. It then tries a list of paths in order, taking the first value that passes the GS1 check digit. The default list is ids.ean, ids.gtin, ean, gtin: the identifier first, the plain payload key as the fallback. A tenant that keeps the key elsewhere names the paths:
openepcis.connectors.connections.brand1.source.options.gtin-paths=ean,article.gtin
A value that fails the check is skipped, not fatal: a tenant keeping a legacy code in one field and the real one in another must not be blocked by the legacy field. Only when no path yields a valid key is the record skipped, and the log line names the path, the value and the defect, so that whoever maintains the data can correct it in the Publisher:
narravero: tridy cVGDZNAHPyJx9Pk3EqGH9z skipped — no payload path carries a valid GTIN.
ids.ean holds '9521890340332' (check digit should be 1); ean holds '9521890340332' (check digit should be 1); gtin holds '9521890340332' (check digit should be 1)
A skipped record blocks nothing. A workspace legitimately holds drafts and test records, and one of them must not hold up the three hundred behind it. The record comes back on its next change, or on the nightly sweep.
The view, and why there is no delta without it
An incremental poll asks for what changed since the last run. Of all the paths Narravero's API exposes, exactly one answers that question: GET /v1/tridys/views/{viewId} with timeStampFrom. The search endpoint POST /v1/tridys takes a context and a content type and lists the records in the workspace with their IDs and timestamps; the payloads are read separately.
So a connection needs a view, and its ID goes into view-id. A view is a server-side selection of payload fields applied to the records of a context, and the view endpoint returns tridyId and payload pairs, which is the shape the connector reads. Without a view the connector falls back to a sweep: it lists the context and then reads every record one by one, two round-trips per record on every poll. Correct, bearable for a small catalog, and not for a few thousand records. A report in the Publisher is a different thing from a view; the view is set up on the Narravero side, so ask your Narravero contact for its ID when the tenant is prepared.
The cursor the connector keeps is an instant. Through a view it is the poll's own start time, because the view answer carries no timestamps, so anything changed while the poll ran is read again next time. Through the sweep it is each record's own timestamp, and the records are handed over oldest first, so the cursor only ever grows. Unchanged records fail on the payload hash and produce no writes; that is the same arrangement as for metasfresh, and it is correct as a complete read.
Polling, and the path to real time
The connector polls Narravero on its interval, and the webhook rung of the diagnosis ladder reads "not applicable" for this source. Narravero's workflow engine can call out on changes: a workTask trigger together with a rest-request task makes exactly the doorbell the other connectors use. On tenants that have the engine licensed, that gives near-real-time updates, and the adapter's fetch path is written so a webhook only needs to name the record; it then enters the same loop the poll enters.
What the mapping carries
The default mapping for this source is one rule, and that is deliberate.
system: narravero
entity: product
rules:
- source: productName
target: productName
kind: localized
An ERP has a fixed schema, and so does a PIM: item_name is always item_name. Narravero's payload is open by design, so there is no field set every tenant shares, and a large default would fit few of them. What is here is the one key from Narravero's own tutorial that maps cleanly onto a GS1 term. The tutorial's third key, price, is deliberately absent: its example value is a formatted display string, "123,32€", and a catalog price term wants an amount and a currency separately. A tenant that keeps a numeric price and a currency in separate keys maps them in its own file.
Everything else belongs in a tenant mapping file, pointed at by mapping-file. The format is the same for every source and is described under how a connector works.
One setting is mandatory for this source. Narravero leaves the language convention to the tenant; a product name may arrive as a bare string. The catalog files names under a language key, so the connection says which language its bare strings are in with source.options.locale. A tenant that follows one of the three internationalisation conventions Narravero's guide offers, suffixes like productName_de, a de.productName map, or a productName.de map, maps the matching paths in its own file.
The Digital Link, and the passport behind it
Every passport in Narravero has an address in the Narravero reader, on the reader's host and under a prefix that belongs to the content type. The QR code the Publisher generates for a template or a record points there.
The connector adds a second address: the GS1 Digital Link, minted under the brand's resolver origin, https://id.example.org/01/09521890340331 for the shirt above. Behind it sits the GS1 Conformant Resolver with a linkset per item, and the Narravero passport is registered in that linkset as gs1:pip, product information page. A consumer who scans the Digital Link lands on the Narravero passport exactly as before. A trading partner, a customs system or a repair shop that resolves the same link gets the master data document, the EN 18223 passport or the EPCIS repository, each under its own link type.
openepcis.connectors.connections.brand1.source.options.reader-url=https://nvero.app/{prefix}/{tridyId}
openepcis.connectors.connections.brand1.source.options.reader-prefix=wdemYj
{tridyId}, {prefix} and {gtin} are available in the template. The prefix is the content type's nfcURLPrefix; it is the segment between the host and the record ID in the QR dialog's URL. Leave reader-url out and no consumer link is published.
The Digital Link in the payload
After every successful publish, the connector writes the minted Digital Link back into the record's payload with a PATCH, under the key digitalLink unless digital-link-key says otherwise.
With that, the link is a placeholder in the DPP template and readable by whoever prints labels. PATCH is the right verb and a deliberate one: it merges, and Narravero's documentation is explicit that ids and media in a PATCH body are not processed, so the write-back touches one key and leaves the identifiers the passport was published under untouched.
A failed write-back is logged and not retried. At that point the passport is already in the catalog and resolvable, and rolling back a successful publication over a convenience field would be wrong.
Labels and carriers
A product can carry either address. The Publisher's QR and NFC tools encode the reader address, which reaches the passport directly. A label that should resolve through the brand's own domain encodes the Digital Link instead; after the first publish it is in the payload, so a label printer or an NFC encoder can read it from there, and the resolver sends the consumer on to the same Narravero passport. Which carrier a brand prints is a decision to take early, together with Narravero, because labels and tags are made once.
Going live
A new connection stays in dry-run, which is the default, and only logs what it would write. Arming it is one deliberate line, dry-run=false. Behind the catalog sit real registrars, GS1 production among them, so a rehearsal that quietly wrote would be worse than no rehearsal.
Narravero contributes products. A Tridy is one identified thing, and lot and serial granularity exist there as payload conventions a tenant may choose rather than as a modelled qualifier, so the connector publishes product records and promotes nothing to an instance. The visibility side then comes on top of that foundation: EPCIS events from the warehouse, the production line or the point of sale, captured through the Odoo addons or the capture API, reachable from the very same identifier that sits on the product.
About the screenshots
The workspace is a Narravero demo tenant on their production service, DPP Publisher version 2.9.6, with the interface shown in Figure 4 created for this page. The three records were sent over that interface with the payloads printed above. The back-link in Figure 8 was written by hand with the same PATCH the connector sends, against a placeholder host, because the demo tenant is not connected to a resolver. The API token is real and is not shown.