[IRS] 🌟🚀 API Change POST /irs/order providing aas identifier as key

[mkanal]

Overview

Explain the topic in 2 sentences

The goal is to enhance the IRS API by allowing it to accept Asset Administration Shell (AAS) identifiers directly, alongside globalAssetIds, as keys in POST requests. This change is meant to simplify data resolution processes for the Trace-X application, reducing the need for manual lookups.

What's the benefit?

By allowing AAS identifiers as input keys, the system eliminates the need for the Trace-X application to receive AAS shell to extract globalAssetIds which is used as input param for irs. This streamlines the API interaction, improving efficiency and reducing error-prone conversions.

What are the Risks/Dependencies?

The main risk is potential ambiguity or conflicts if both globalAssetId and AAS identifiers are provided simultaneously. This can lead to issues with result resolution or misinterpretation, necessitating robust error handling.

Detailed explanation

Current implementation

The current implementation of the IRS API only accepts globalAssetId as a key in the POST /irs/orders request. It does not provide an option to pass an AAS identifier directly, which forces clients like Trace-X to resolve AAS identifiers to globalAssetIds before making the API call.

Proposed improvements

The enhancement proposes to allow the IRS API to accept both AAS identifiers and globalAssetIds as keys, with clear differentiation in how they are handled. Three options are outlined:

• Option A: Add a separate identifier field alongside globalAssetId.
• Option B: Combine both identifier types in a single field with a clear prefix.
• Option C: Keep the current implementation but accept both key types with no distinction, though this would limit error handling capabilities.

Feature Team

Contributor

• Cofinity-X @rogocof
• Cofinity-X @mkanal

Committer

• @ds-jhartmann
• @ds-mwesener
• @ds-lcapellino

---

User Story

As an IRS api user,
I want the POST /irs/orders API to accept an AAS (Asset Administration Shell) identifier as a key,
so that the Trace-X application does not need to resolve the aas identifiers to globalAssetIds for each of the requested Twins

Specification

• ADR record of issue (X) defines the api parameter to be used analogous to new /irs/jobs api

Option A:

{
  ...
  "key": {
    "bpn": "BPNL0123456789XX",
    "globalAssetId": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
    "identifier": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
  }
}

The identifier is qualified by key. globalAssetId as globalAssetId and identifier as identifier

Option B:

{
  ...
  "key": {
    "bpn": "BPNL0123456789XX",
    "id": "<globalAssetId|identifier>:urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
  }
}

The identifier is qualified inside value as prefix: ”globalAssetId: ” or ”identifier:”

Option C:

No changes in api - key id accepted in key.

disadvantage: no specific error handling because the system does not know the type of the key so it is not possible to say whether there is no result for the globalAssetId or the identifier.

{
  ...
  "key": {
    "bpn": "BPNL0123456789XX",
    "id": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
  }
}

GET /irs/job/{id} extend

 "job": {
    "globalAssetId": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0",
    "aasIdentifier": "<aasIdentifier>"
    "id": "e5347c88-a921-11ec-b909-0242ac120002",
    "lastModifiedOn": {},
    ...
    },

Acceptance Criterias

• Extending job response with correct globalAssetId in case job is started with identifier
• API accepts aasIdentifier(AAS Identifier) as an additional input parameter.
• The IRS must be able to process the aasIdentifier and use it to query the appropriate data or provide a suitable job response.
• GET /irs/order/{id} "job": {..} response is extended with aasIdentifier information
• In case a malformed aasIdentifier is provided, the api return a suitable and comprehensible error message.
• In case globalAssetId and aasIdentifier are passed in parallel, the system return a suitable and comprehensible error message.

---

Test Cases

Test Case 1

Steps

1. Do something
2. Click something
3. Add something

Expected Result

1. Expectation
2. Expectation
3. Expectation

Architectural Relevance

The following items are ensured (answer: yes) after this issue is implemented:

• This feature aligns with our current architectural guidelines
  • Data Sovereignty: All data sharing activities across company boundaries follow the Catena-X Regulatory Framework, in particular the Data Exchange Governance, and the Dataspace Protocol via a compliant Connector (like the tractusx-edc or similar, see Connector KIT)
    • CX-0010 Business Partner Number
    • CX-0013 Identity of Member Companies
    • CX-0018 Data Space Connectivity (EDC)
    • CX-0049 DID Document Schema
    • CX-0050 Framework Agreement Credential
    • CX-0149 Verified Company Identity
  • Interoperability: Digital Twins are used (compliant to the Digital Twin KIT and the Industry Core KIT)
    • CX-0001 EDC Discovery API
    • CX-0002 Digital Twins in Catena-X
    • CX-0018 Data Space Connectivity (EDC)
  • Data Format:
    • The data model is based on a published Semantic Model
• The impact on the overall system architecture has been assessed. The Feature does not require changes to the architecture or any existing standard? Please have a look here on the overarching architecture
• Potential risks or conflicts with existing architecture has been assessed

Justification: (Fill this out, if at least one of the checkboxes above cannot be ticked. Contact the Architecture Management Committee to get an approval for the justification)

Additional information

• I am aware that my request may not be developed if no developer can be found for it. I'll try to contribute a developer (bring your own developer)

[stephanbcbauer]

Some hints from Release Management (@ther3sa) and Tractus-X Project Lead (@stephanbcbauer)

• Status currently in Backlog -> Since for Backlog some requirements are missing ... please update them
• Please add missing sections from the feature template, or fill them out
• Please add assignee (overall responsible person who drives the feature)