The metasfresh connector

How the connector reads metasfresh over its REST API v2: the API token and its role, where GTIN and GLN come from, the connection settings, what is published for products and business partners, the default mapping, polling without webhooks, and the optional back-link through External References.

metasfresh is an open source ERP that already keeps the two GS1 keys a catalog needs in places you would expect: the GTIN on the product and the GLN on the business partner's locations. The connector reads products and business partners through the metasfresh REST API v2 and publishes them to the OpenEPCIS catalog, products under their GTIN and business partners under their GLN. A scan of the product's GS1 Digital Link then reaches its master data and the passport derived from it.

The connector talks to metasfresh exclusively through the REST API v2. metasfresh is licensed GPL-2.0-only, and keeping to the published interface keeps the connector clear of it. For operations this means that nothing is installed on the metasfresh side. The connector needs an API token and read permissions for the user behind it. The general mechanics of polling, mapping and publishing are explained in how a connector works.

The API token

metasfresh authenticates API calls with a token that is stored on a user and sent as the bare value of the Authorization header, without a Bearer prefix, as the metasfresh documentation describes it. The token is created in the user record on the Authentication Tokens tab: add an entry there and choose a role, whose permissions the token inherits exactly.

A dedicated integration user, for example openepcis-connector, with a narrow role is worth the small effort over a personal account. The token then survives staff changes, and the log makes clear who is reading. The role needs read access to business partners and products. If the connector should also record its back-link in metasfresh, as described further down, write access to external references is added and nothing else. The connector reads metasfresh and writes to the OpenEPCIS catalog, and it never writes business data into the ERP.

The connection

A connection names one metasfresh and one catalog:

openepcis.connectors.connections.werk2.source.type=metasfresh
openepcis.connectors.connections.werk2.source.url=https://mf.example.test
openepcis.connectors.connections.werk2.source.auth.kind=static-token
openepcis.connectors.connections.werk2.source.auth.token=<the token, without prefix>
openepcis.connectors.connections.werk2.source.options.locale=de
openepcis.connectors.connections.werk2.target.resolver-url=https://id.example.test
openepcis.connectors.connections.werk2.target.gcp-prefixes=9521234
openepcis.connectors.connections.werk2.target.offline-token=<platform offline token>
openepcis.connectors.connections.werk2.target.economic-operator-gln=9521234000006
openepcis.connectors.connections.werk2.dry-run=true

source.url is the origin of the metasfresh instance; the connector adds the /api/v2 paths itself. The static-token kind sets the literal header value, so the token goes in exactly as metasfresh issued it. source.options.locale names the language of texts that arrive as a plain string, so that they are filed in the catalog under that language key. target.economic-operator-gln sets that GLN as the manufacturer on every product whose source names none, which the EN 18223 passport requires.

The token and the offline token belong in a Kubernetes secret; the block above only names the keys. How the offline token is issued, and what revoking it does to a running connection, is covered in Integration Tokens.

Where GTIN and GLN come from

The GTIN is read from the product's ean field. A product with ean set to 9521234000013 is published under /01/09521234000013. Why the GTIN has to be a key of its own, and how it relates to the product's own number, is explained in identifiers: GTIN and SKU.

The GLN of a business partner comes from its locations. The connector takes the first address whose GLN passes the GS1 check digit, so a mistyped GLN on a delivery address never hides a correct one on the billing address. Products without a valid EAN and business partners without a valid GLN are skipped during sync and named in the log. They block nothing, and the next poll picks them up once the data is corrected in metasfresh.

What gets published

Each product with a valid EAN becomes a product document at /01/<gtin>, and each business partner with a valid location GLN becomes an organisation document under that GLN. metasfresh contributes master data at the class level: the connector publishes no batch or serial documents for this source.

The default mapping

The default mapping carries only what every metasfresh installation holds. Every rule runs from metasfresh to the catalog, and nothing in the catalog is written back into metasfresh's fields. The GTIN and the GLN are read by the adapter itself, because they say which record this is, so they do not appear in the mapping file.

For products, name becomes productName and description becomes productDescription. For business partners, the partner's name becomes organizationName. All three are mapped as localized values. metasfresh is multilingual, and the public documentation leaves open whether the v2 answer carries these texts as a plain string or as a language map. A language map passes through as it is, and a plain string is filed under the language that source.options.locale names. A website is left out because the catalog's organisation document has no field for one.

Everything else goes into a copy of the default mapping, entered as the connection's mapping-file. The format is the same for every source and is described under the mapping format.

How sync works

metasfresh offers no webhooks, so the connector polls, every 15 minutes unless the connection's poll-interval says otherwise. Every poll is built to be correct as a complete read. The connector passes the API a since parameter as a shortcut, and records whose payload hash matches the last publication produce no write. At night a full reconciliation across all connections runs on top of the delta polls. It can be switched off per connection with full-sync-enabled=false for a source that cannot tolerate the full read.

Before the first run, the diagnosis ladder shows what already works:

curl https://<connectors-host>/connections/werk2/diagnostics

Its webhook step reads "not applicable" for metasfresh connections. That is expected, since there is nothing to check.

After every successful publish, the connector can store its link in metasfresh itself, through the External References API, under the system name OpenEPCIS. The reference it stores is the GS1 key. The key is the stable identity, the Digital Link can always be derived from it, and a stored URL would go stale if the resolver moved. The feature is off by default and is switched on per connection:

openepcis.connectors.connections.werk2.source.options.record-external-references=true
openepcis.connectors.connections.werk2.source.options.external-system-name=OpenEPCIS

The second line is optional and only needed for a different system name. Before the back-link goes live for the first time, check the request shape once against the Swagger description of your own instance, because the public documentation leaves some details open.

Going live

A new connection starts with dry-run=true, which is the default, and only logs what it would write. Read that log carefully, because real registrars sit behind the catalog, GS1 production among them, and arming the connection takes the single line dry-run=false. Test data should carry keys from the GS1 test range only, GTINs and GLNs starting with 952, until the connection is meant to publish real products.

dry-run is on by default: a connection publishes nothing until you set dry-run=false for it.

Last updated: