Catena-X support

VERA supports the data exchange with Catena-X. It provides the ability that any partner can request specific assets or digital twins via VERAs connected EDC. The requirements to request data from other EDCs is that the consumer (partner or organization) know the providers BPN and the specific assetId or Digital Twin ID which should be requested.

In VERA this request is called DataRequest and can be used with the DataRequest API. In the following examples we will explain, how VERA handles the communication with the providers EDC to retrieve the requested Asset.

Compatible CatenaX Standards

VERA currently supports resolving the following CatenaX Standards from other EDCs:

AssetIds VERA can negotiate and transfer a specific assetId from a given BPN. The transferred data will be stored in the DataRequest
EcoPass/BatteryPass VERA can resolve a BatteryPass provided by a BPN. For this you need to provide the CatenaX related standard ID in the format of CX:manufacturerPartId:partInstanceId

Integrated CatenaX ecosystems

The following CatenaX ecosystems are available in VERA:

CofinityX Preprod Environment

Entities

DataRequest

The DataRequest contains the necessary data which is required to fetch and obtain data from a remote provider. To fetch a specific asset or digital twin you need the following details:

AssetId or EcoPass Digital Twin ID
ProviderBPN (Only needed when resolving an Asset)

Creating a DataRequest

In the DataRequest everything gets handled with the /data-requests endpoint. Since VERA can at the moment only request and receive data from other parties, there is no "answering" of "incoming" data requests at the moment.

Lets assume, that you want to receive an AssetID 123 from the BPN BPNL000000000002. This document assumes also, that the target BPN allows to fetch this asset from the BPNs' catalog and initiate a negotiation for it.

To create a Data Request, you need to call the Endpoint: POST /data-requests with the following properties:

{
    "assetId": "123",
    "provider": "BPNL000000000002"
}

This request then returns the following payload and sets the DataRequest to state Created

{
    "meta": {},
    "data": {
        "id": "41107f0e-46e9-46b6-ae73-275a21b56bcf",
        "createdAt": "2024-03-15T07:01:14.303Z",
        "updatedAt": "2024-03-15T07:01:14.303Z",
        "assetId": "123",
        "trackingId": "5bbaa76f-befb-4063-8c6d-f0320726332c",
        "state": "Created",
        "consumer": "BPNL000000000001",
        "provider": "BPNL000000000002",
        "data": {},
        "organizationId": "468fa2c5-9cd5-4fd6-8f87-e6bebe3e63ea"
    }
}

Now the VERA takes the request and the defined AssetId and Provider BPN to execute the following steps on the CatenaX Ecosystem:

sequenceDiagram VERA->>CatenaX EDC Discovery: Fetch EDCs for BPN CatenaX EDC Discovery->>VERA: Return list of registered EDCs VERA->>VERA EDC: Fetch Asset catalog from registered EDCs VERA EDC->>Provider EDC1: Request Assets Provider EDC1->>VERA EDC: Return empty catalog VERA EDC->>Provider EDC2: Request Assets Provider EDC2->>VERA EDC: Return requested Asset Offer VERA EDC->>VERA: Return asset Offer VERA->>VERA EDC: Initiate Contract & Transfer negotiation VERA EDC->>Provider EDC2: Start Negotiation for Asset Provider EDC2->>VERA EDC: Finish Negotiation VERA EDC->>VERA: Notify about finished Negotiation VERA->>Provider EDC2: Fetch Asset Provider EDC2->>VERA: Return Asset Payload VERA->>VERA: Persist Payload<br>in DataRequest

VERA first tries to discover all registered EDCs for the given provider against the ecosystems central EDC discovery component. When the component then returns the list of registered EDCs for the BPN, VERA will contact all EDCs and query their registered catalog to see if the specific EDC has the requested asset registered.

When one EDC has the requested asset registered, VERA will then start the negotiation phase of the asset. This includes the negotiation of a contract and afterwards the transfer initiation. When VERA receives the successful negotiation and transfer of the asset, it will fetch the assets payload from the providers EDC and will store the payload in DataRequest's data property.

When any error occurs in this process, the DataRequest's state will move to Failed and will give a detailed error message in the data property.

Fetching the data

After the whole transfer process finishes, the data property gets updated in the DataRequest. When you fetch afterwards the DataRequest with its associated ID from the Endpoint: GET /data-requests/:uuid, you will find the data attached to the DataRequest

{
    "meta": {},
    "data": {
        "id": "41107f0e-46e9-46b6-ae73-275a21b56bcf",
        "createdAt": "2024-03-15T07:01:14.303Z",
        "updatedAt": "2024-03-15T07:01:14.303Z",
        "assetId": "123",
        "trackingId": "5bbaa76f-befb-4063-8c6d-f0320726332c",
        "state": "Finished",
        "consumer": "BPNL000000000001",
        "provider": "BPNL000000000002",
        "data": {
            "userId": 1,
            "id": 3,
            "title": "fugiat veniam minus",
            "completed": false
        },
        "organizationId": "468fa2c5-9cd5-4fd6-8f87-e6bebe3e63ea"
    }
}

State Machine of the DataRequest

The DataRequest can have the following state's and also transition in the following possibilities:

stateDiagram-v2 [*] --> Created Created --> Failed Failed --> [*] Created --> Processing Processing --> Failed Processing --> Declined Declined --> [*] Processing --> Complete Complete --> [*]

Possible Errors

During the processing of the DataRequest it can happen that errors occur. The following list provides the possible errors which can happen during processing:

An error occurred while fetching contract agreements from EDC
An error occured while discovering EDCs for BPN
No EDC found for provider=BPNLXXXX
No asset found for assetID=XXX in the provider catalog
An error occurred while initiating contract negotiation with EDC
An error occurred while fetching contract negotiation from EDC
An error occurred while initiating transfer
Failed to fetch transfer data from EDC