The AAS connector: BaSyx and EDC

How the AAS connector reads Asset Administration Shells from Eclipse BaSyx, directly or through an Eclipse Dataspace Connector, and publish them to the OpenEPCIS catalog under a GS1 Digital Link with an EN 18223 passport behind it.

Manufacturers in machinery, electrical equipment and automotive supply often keep their product data in an Asset Administration Shell. The nameplate, the technical data, the carbon footprint and the handover documents sit in standardised submodels, served by Eclipse BaSyx or a comparable AAS server, and in a dataspace such as Catena-X they are offered to partners behind an Eclipse Dataspace Connector with a usage policy attached.

The AAS connector builds on that work. It reads shells and submodels and publishes each asset to the OpenEPCIS catalog under a GS1 Digital Link, which then leads to the GS1 master data document, an EN 18223 passport and the EPCIS events recorded for the item. Your engineers keep maintaining the data in the AAS, and the QR code on the product makes it reachable for anyone who scans it.

Availability: the AAS connector is available on request. AAS onboarding involves more than a token and a URL: asset IDs, submodel versions, identity in the dataspace and accepted policies differ from plant to plant, so we configure the connection with you and keep it out of the self-service settings in the app. Write to us with the AAS server or dataspace you want to connect.

What AAS does well, and what EPCIS adds

The Asset Administration Shell is the digital twin of Industrie 4.0, and for that purpose it is a very good one. Its submodel templates give a machine, a component or a product a standardised nameplate, technical data, documentation and a carbon footprint, and a shell for a single instance can carry its serial number and its own operating values. Engineers, service technicians and buyers who want to know what an asset is and what it can do find it there in a form every tool understands, and that is why we read it as a source.

It is one kind of digital twin among several, though, and the word means quite different things depending on who uses it. A simulation engineer thinks of a physical model that behaves like the real machine. Someone who has trained machine learning models on production data thinks of a twin as a model that has learned from the history of many similar assets and predicts what this one will do next: when a bearing will fail, how a battery ages, which lot will cause quality problems. A regulator thinks of a product passport that follows an item through its life. We have written more about this range of views in the digital twin continuum.

What these views share is that they depend on history. A shell holds the state of one asset as its owner maintains it, while the history of that asset across companies lies outside its scope: which batch of material went into it, at which plant it was assembled, when it was packed onto which pallet, who shipped it to whom and in what condition it arrived. Those are events, each with a time, a place, a reason and the parties involved, recorded by many different companies along the chain, most of which never touch the shell. A predictive model learns from exactly such records, and a passport has to show them. EPCIS 2.0 is the GS1 standard built for this record, and the OpenEPCIS repository keeps it under the same GS1 identifiers that are printed on the goods.

This matters more with every new regulation. The UN Transparency Protocol (UNTP) describes a product passport as a set of linked credentials, and its traceability events follow the EPCIS event model, so a chain recorded in EPCIS translates directly into UNTP. Requirements on recycled and certified content point the same way. Claiming a share of recycled or certified material under a mass balance approach means following quantities through every transformation and every shipment, from the input lots to the output lots, and a passport can only prove such a claim when those transformation and shipping events exist and can be checked. A nameplate and a technical data sheet describe the finished product; the events show how it was made.

Dataspaces such as Catena-X solve a different problem well: sharing confidential data between two companies under a negotiated contract. For a traceability record the model is heavy. Every exchange runs through a connector on both sides, a registered identity, a catalog request and a contract negotiation, and that is a lot to ask of a farm, a recycler, a carrier or a small supplier who only needs to report that a lot left their yard. EPCIS lets each party report its own events through one interface with an access token, and the Digital Link on the product gives anyone who scans it a way into the record, with the access tiers deciding who sees what.

Trust is the usual argument for a dataspace: you know who your counterpart is, and a contract governs what they may do with your data. We get to the same assurance with verifiable credentials, which travel with the data and need no connector at all. A passport can be issued as a W3C Verifiable Credential, signed by the platform's issuer under its did:web identity, with a status list that shows whether it has been revoked and a signed list of trusted issuers that a verifier checks against. Anyone who receives the passport, whether a customs system, a recycler or a buyer three steps down the chain, can verify who issued it and that nothing was changed, using our public verifier or any standard library. Access to restricted fields is granted by presenting a credential over OpenID for Verifiable Presentations, so a partner proves a role once and is not onboarded into anything. The details are in signed passports.

So we use each standard for what it does best. The AAS connector brings the engineering description into the catalog, EPCIS carries what happens to the product from raw material to end of life, and both meet under one GS1 Digital Link. Where partners do exchange through a dataspace, the connector reads from it as well, as the next section describes.

Two ways in

Each connection reads shells either directly from an AAS server or through a dataspace.

The direct mode is meant for an AAS server you operate yourself or one a partner opens to you. The connector uses the HTTP API of IDTA specification Part 2: it lists shells from the AAS repository or the AAS registry, follows each shell's submodel references, and reads the submodels from the submodel repository. Authentication is a static token or an OIDC client credential, since AAS servers in a plant usually sit behind Keycloak or Entra ID. For a manufacturer who wants passports for their own products, this is the usual starting point.

The dataspace mode is meant for shells a partner offers behind an EDC, and here the connector acts as an ordinary data consumer. It looks the asset up in the provider's Digital Twin Registry, reads the subprotocolBody of the submodel descriptor (id=<assetId>;dspEndpoint=<url>, the pattern from CX-0002), requests the provider's catalog over the Dataspace Protocol, negotiates a contract against the offered policy, receives an Endpoint Data Reference and reads the submodel through the provider's data plane with the token from that reference. The consumer EDC acts under your own participant identity, so the contract the provider sees is a contract with you.

Once a submodel has been fetched, both modes continue the same way: mapping, GS1 key, publish and linkset follow the loop every connector runs, described under how a connector works.

From an asset to a GS1 key

An AAS identifies its asset by a globalAssetId and by a list of specificAssetIds, name and value pairs such as manufacturerPartId, partInstanceId or a customer part number. None of them is a GTIN by definition, so the connection says where the GS1 key lives, as an ordered list of names:

openepcis.connectors.connections.plant1.source.options.gtin-keys=gtin,globalAssetId
openepcis.connectors.connections.plant1.source.options.serial-key=partInstanceId
openepcis.connectors.connections.plant1.source.options.lot-key=batchId

The connector takes the first value that is a valid GTIN, with the check digit verified, or a GS1 Digital Link from which it can read one. A globalAssetId that is already a Digital Link, such as https://id.example.org/01/09521234000013/21/A-0042, therefore needs no further configuration. When no key yields a valid GTIN the shell is skipped, and the log line names each key, its value and why it failed, so the person who maintains the shell can fix it there.

The shell's assetKind decides the granularity. A shell of kind Type becomes a product at /01/<gtin>. A shell of kind Instance becomes a single item at /01/<gtin>/21/<serial>, or a batch at /10/<lot> when the connection names a lot key and the shell carries it. An instance whose type shell is also in scope inherits the product data from it, so the nameplate is maintained once per type.

What the submodels carry

Submodels are matched by their semanticId, which is stable across servers and languages, and the mapping file names the elements inside a submodel by their idShort path. The default mapping covers the IDTA templates that carry passport data:

IDTA submodel templateGoes to
Digital Nameplate for Industrial Equipment (IDTA 02006)Manufacturer name and address, product designation, serial number, year of construction, country of origin, markings
Technical Data (IDTA 02003)General product information and product classification (ECLASS or IEC CDD), carried as additional properties
Carbon Footprint (IDTA 02023)Product carbon footprint per declared unit, life cycle phases, calculation method
Handover Documentation (IDTA 02004)One linkset entry per document, typed by its VDI 2770 class: manual, safety data sheet, declaration of conformity
Contact Information (IDTA 02002)The economic operator and its contact point

A shortened mapping for the nameplate looks like this:

system: aas
entity: product
submodels:
  - semanticId: https://admin-shell.io/idta/nameplate/3/0/Nameplate
    rules:
      - source: ManufacturerName
        target: manufacturer.name
        kind: localized
      - source: ManufacturerProductDesignation
        target: productName
        kind: localized
      - source: CountryOfOrigin
        target: countryOfOrigin
      - source: AddressInformation/Street
        target: manufacturer.address.streetAddress
        kind: localized

Values of a MultiLanguageProperty keep their language tags in the catalog. Submodels the mapping does not mention are left alone, and if you use your own submodels or a different template version, the matching block goes into your connection's mapping file, in the same format all connectors use.

The passport needs a manufacturer and a Digital Link; the nameplate supplies the first and the connector mints the second, so a shell with a readable nameplate produces a complete passport on the first publish.

Configuration

A connection in direct mode against a BaSyx server:

openepcis.connectors.connections.plant1.source.type=aas
openepcis.connectors.connections.plant1.source.options.mode=direct
openepcis.connectors.connections.plant1.source.url=https://aas.example.org
openepcis.connectors.connections.plant1.source.options.registry-url=https://aas-registry.example.org
openepcis.connectors.connections.plant1.source.auth.kind=oidc-client
openepcis.connectors.connections.plant1.source.auth.token-url=https://login.example.org/realms/plant/protocol/openid-connect/token
openepcis.connectors.connections.plant1.source.auth.client-id=openepcis-connector
openepcis.connectors.connections.plant1.target.resolver-url=https://id.example.org
openepcis.connectors.connections.plant1.target.gcp-prefixes=9521234

The same connection reading from a partner's EDC:

openepcis.connectors.connections.supplier1.source.type=aas
openepcis.connectors.connections.supplier1.source.options.mode=edc
openepcis.connectors.connections.supplier1.source.options.dtr-url=https://dtr.supplier.example
openepcis.connectors.connections.supplier1.source.options.provider-id=BPNL000000000001
openepcis.connectors.connections.supplier1.source.options.consumer-management-url=https://edc.example.org/management
openepcis.connectors.connections.supplier1.source.options.accepted-policies=<policy IDs you have approved>
openepcis.connectors.connections.supplier1.target.resolver-url=https://id.example.org

In dataspace mode the connector drives a consumer EDC through its management API, and that EDC speaks the Dataspace Protocol with the provider. Under accepted-policies you list the policies your legal team has approved, and the connector accepts offers under those policies on its own. Offers under any other policy are skipped and reported, so that a person who has read the terms decides about them. Credentials go into a Kubernetes secret as for every other source; the platform credential of the connection comes from Integration Tokens.

Staying in sync

AAS Part 2 has no change feed, so the connector polls. It pages through /shells with the cursor the API returns and compares a hash of each shell and its submodels with what the catalog holds, so unchanged shells cause no writes. As with the other sources, a nightly full sweep picks up anything the regular polls missed.

If your BaSyx server publishes change events over MQTT, the connection can subscribe to them and pick up changes within seconds. The connector treats an event the way it treats a webhook from an ERP system: as a hint to read that shell again, with the data itself always fetched from the server.

In EDC mode a negotiated contract and its Endpoint Data Reference are kept and reused until the reference expires, so a poll does not renegotiate for every submodel.

What flows back

After a successful publish the connector can write the minted Digital Link back into the shell as a specificAssetId named gs1DigitalLink, which needs write access to the AAS repository and is therefore off by default. In EDC mode nothing is written back; the provider owns its shells.

Lookups also work the other way round. The resolver answers AAS discovery queries for a Digital Link, so an AAS client that starts from the QR code on a product finds the shell, and a GS1 client resolving the same link gets the master data, the passport or the events.

Getting started

We set up the first connection together with you, usually with a handful of your product types. Before anything goes live you see exactly which products would be published under which Digital Link and with which data, and only when that looks right does the connection start publishing.

Instances and partner data follow from there. If you want to read shells from suppliers in Catena-X or another dataspace, your company needs to take part in that dataspace; until then the direct connection to your own AAS server works on its own. The connector carries master data, and events about an item, from the warehouse or the production line, attach to the same Digital Link through the other connectors or the capture API.

Last updated: