FOSS IRS Application ‐ Development a Frontend for the IRS (ItemRelationshipService) API using GenAI - eclipse-tractusx/tutorial-resources GitHub Wiki

Table of Contents

Objective

Visualization of an Industry Core Standard-Compliant PartChain, provided in the CATENA-X Data Space according to Data Sovereignty Principles.

What is this challenge about?

This challenge focuses on developing a web client, powered by GenAI, for interacting with the IRS and visualizing asset relationships according to Catena-X standards. The challenge mainly relates to the Industry Core IC ( CX-0127 Part Instance 2.0.0 ) standard.

Challenge 1: IRS Integration and Initial Visualization

Build a GenAI powered web client frontend, integrate it with the IRS, initiate IRS jobs, and display responses (JobResponses) in the UI.

Challenge 2:

Extract and structure twin relationships between companies, displaying asset identifiers and connections in a graph view.

Challenge 3:

Enrich the visualization with detailed Industry Core aspects (such as JIS (JustInSequence), SerialPart, and Batch), providing comprehensive insight into asset relationships.

This challenge offers an opportunity to work and understand core concepts with C-X standards and data visualization in asset tracking. This challenge aims to demonstrate the ease and potential of generating business value and benefits through contributions to an open-source application, highlighting both the simplicity and satisfaction that can be achieved in this collaborative process.

Surrounding Conditions

How to prepare for the challenge

FAQ

Question Answer
Why is this event a challenge and not a workshop? Our goal with this challenge is to provide you with an empirical experience of how quickly results and value can be delivered. By implementing the Industry Core Standard practically and visualizing it, you'll gain a hands-on understanding of its principles.
What's the goal of this stream? The goal of this stream is to showcase the value and benefits of using Industry Core standards in consuming a part chain, while demonstrating the impact of contributing to an open-source application.
Who is the target audience of the stream? Developers, IT consultants, tech enthusiasts, AI enthusiasts, and anyone interested in the topic
What should I bring to the event? Bring your DEV machine, admin rights to that machine, a working GitHub account and your favorite IDE
Where can I find the Catena-X standards? You can find released versions here: CX-Jupiter Standard library
When preparing for the challenge, what should I focus on? Refer to the section How to prepare for the challenge

Details Challenge 1: IRS Integration and Initial Visualization

Goals:

  • Getting familiar with IRS API
  • Understanding elements of the JobReponse
  • Visualize the semantic artifacts from the JobReponse
  • Get in contact with the semantic models, shells of the industry core standard

Procedure:

  1. Develop a user interface (UI) for a web application.
  2. Integrate the IRS API within the web application. 2.1 https://eclipse-tractusx.github.io/item-relationship-service/docs/swagger-ui/index.html
  3. Register an IRS job with all required semantic models.
  4. Check the JobResponse for completion.
  5. Retrieve the IRS JobResponse.
  6. Visualize the JobResponse JSON in the UI.
sequenceDiagram
    actor  user as User
    participant api as IRS API


    user ->> api: Register job : POST /irs/jobs
    activate api
    api -->> user : (201) id
    deactivate api

    user ->> api: Get Job By Id : GET /irs/jobs/{id}
    activate api
    api -->> user : (200) JobRepoonse (json)
    deactivate api

IRS API Flow

Register Job

In the IRS, a job can be registered to retrieve a distributed PartChain within the data space. To initiate this, an appropriate job is registered. The desired job result from the data space can be precisely specified by using parameters that accurately define the outcome of the query.

POST /irs/jobs

{
  "aspects": [
    "urn:samm:io.catenax.single_level_bom_as_built:3.0.0#SingleLevelBomAsBuilt",
    "urn:samm:io.catenax.single_level_bom_as_built:3.0.0#SerialPart",
    "urn:samm:io.catenax.single_level_bom_as_built:3.0.0#Batch",
    "urn:samm:io.catenax.single_level_bom_as_built:3.0.0#JustInSequence",
  ],
  "auditContractNegotiation": true,
  "bomLifecycle": "asBuilt",
  "callbackUrl": "https://hostname.com/callback?id={id}&state={state}",
  "collectAspects": true,
  "depth": 3,
  "direction": "downward",
  "key": {
    "bpn": "${BPNL}",
    "globalAssetId": "${globalAssetId}"
  }
}
No BPNL globalAssetId
BPNL... urn...
Request job response

Polling a job until job state is equals "COMPLETED" ( "job":"state": "COMPLETED")

GET /irs/jobs/{id}?returnUncompletedJob=true
Object Description
"job" Main process for retrieving asset information Includes: Creation and completion dates (createdOn, completedOn) / Possible error message exception) / requested parameters / job status (state) / Summary of asynchronously retrieved items (summary)
"relationships" Describes the relationship between objects within the Catena-X ecosystem. A parent object (catenaXId) is linked to a child object (childCatenaXId). Quantity of the child element (quantity)
"shells" Includes metadata about a digital twin. Subordinate information includes submodelDescriptors, providing information of attached Semantic models
"submodels" A submodel is a structured data model that represents specific aspects or characteristics of an asset or product. Submodels provide detailed information about different aspects of the asset, such as technical specifications, lifecycle data, material composition, or service-related information.
"tombstones" Documents errors or issues in processing twins or submodels. Includes: catenaXId of the affected object. Request URL (endpointURL)
The processingError object describes the issue's cause (e.g., schema validation error).

Details Challenge 2:

%%{
  init: {
    'flowchart': { 'curve': 'linear' },
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#00A5E1',
      'primaryTextColor': '#fff',
      'primaryBorderColor': '#8A9DB3',
      'lineColor': '#374656',
      'secondaryColor': '#D7E9F4',
      'tertiaryColor': '#F0F8FF'
    }
  }
}%%
flowchart LR
    subgraph "Wayne Enterprises"
       TWIN_A((   Vehicle   )) --> SLBAB(SingleLevelBOMAsBuilt) 
    end
    subgraph "Umbrella Corporation"
        SLBAB--> TWIN_B((Transmission))
        TWIN_B--> SLBAB2(SingleLevelBOMAsBuilt) 
    end
     subgraph "Stark Industries"
        SLBAB2--> TWIN_C((GearBox Shaft))
    end

Details Challenge 3:

%%{
  init: {
    'theme': 'base',
    'flowchart': { 'curve': 'stepAfter' },
    'themeVariables': {
      'primaryColor': '#00A5E1',
      'primaryTextColor': '#fff',
      'primaryBorderColor': '#8A9DB3',
      'lineColor': '#374656',
      'secondaryColor': '#D7E9F4',
      'tertiaryColor': '#F0F8FF'
    }
  }
}%%
flowchart LR
    subgraph "Wayne Enterprises"
      direction TB
      TWIN_A((   Vehicle   )) --> SLBAB(SingleLevelBOMAsBuilt)  
      TWIN_A -.-> SerialPart(SerialPart)
    end
    subgraph "Umbrella Corporation"
        direction TB
        SLBAB(SingleLevelBOMAsBuilt)  --> TWIN_B((Transmission))
        TWIN_B --> SLBAB2(SingleLevelBOMAsBuilt)  
        TWIN_B -.-> Batch(Batch)
    end
     subgraph "Stark Industries"
        direction TB 
        SLBAB2--> TWIN_C((GearBox Shaft))
        TWIN_C -.-> JIS(JustInSequence)
    end