¶ Industry Core: Development of a Frontend for the IRS API Utilizing GenAI for Visualizing Industry Core-Compliant Part Chains
NOTE: This challenge will be repeated in 2-hour blocks with the same content.
¶ Objective
Visualization of an Industry Core Standard-Compliant PartChain, provided in the CATENA-X Data Space according to Data Sovereignty Principles.
¶ What is this Workstream about?
This workstream focuses on developing a web client, powered by GenAI, for interacting with the IRS and visualizing part chains according to the Catena-X standards. The challenge focusses on the Industry Core ( CX-0127 Part Instance 2.0.0 ) standard.
¶ Phase 1: Integration of IRS and visualization of IRS JobResponse
This Phase 1 is to develop a web client (using GenAI), integrate it with the IRS, initiate a job, and display the job response (JobResponses) in UI.
¶ Phase 2: Visualization of Part Chain between twins
Extract, structure, and visualize twin relationships in an interactive graph showcasing nodes (twins) and edges (connections) annotated with relationship types. Attach AAS shell attributes and identifiers to the twins.
¶ Phase 3: Visualization of Part Chain with related submodels
Enrich the visualization with detailed Industry Core aspects (such as JIS (JustInSequencePart), 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.
¶ Outcome and Voting
As soon as you are finished, please take a screenshot of your result and name it “firstname_lastname.png”. Permitted file formats are PNG or JPG. Send it by email to tractus-x_community_days@doubleslash.de. After submitting your screenshot, you will automatically be included in the voting.
¶ Surrounding Conditions
- IRS Repository
- IRS OpenAPI3.1 (Swagger)
- Architecture Documentation (arc42)
- Administration Guide
- Tutorial Resources
- AI Assistent (Support for inexperienced developers)
¶ How to prepare for the challenge
- Ensure that your DEV machine has at least 16 GB of RAM as well as a quad-core CPU
- Install your favorite IDE to your local DEV machine
- Ensure that you have access and logged in to your GitHub account
- Ensure Node.js and npm installed on your system. (Download: https://nodejs.org/)
- Install packages
npm install -g express http-proxy-middleware
- Install packages
- (Optional) Install Insomnia REST on your local machine (Interacting with IRS API)
- Polish up on OpenAPI3.1.0 and frontend web libraries like React, Angular Framework, Node,js, etc.
- Familiarize yourself with the IRS OpenAPI
- Choose your favorite LLM and the GenAI client to be used (GPT-4o,Llama, RoBERTa), (ChatGPT, Tabnine)
- Premium Account recommended to avoid token or character limitations
- Familiarize yourself with the Industry Core KIT
- Familiarize yourself with the MUST CX-0127 Industry Core: Part Instance 2.0.0 and OPTIONAL CX-0126 Industry Core: Part Type 2.0.0
¶ 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 |
| What to do if I have CORS issues and cannot connecto the Item-Relationship-Service? | If you have problems, refer to this example of how to setup a proxy. |
| IRS API responses does not contain any submodel or shells, only tombstones | In case of issues with the IRS, you can use a WireMock instance which returns the same data. In this case, replace the IRS base URL in your proxy with this URL: https://irs-mock-ic.a3fb75c369e540489a65.germanywestcentral.aksapp.io |
¶ Common Issues
| Issue | Solution |
|---|---|
| AI assistant keep suggesting the wrong solution | In case of any unexpected behavior, simply start a new conversation and paste the instruction for your current phase into it. Provide the required files and continue with the steps. |
| I receive a 401 unauthorized | Proxy is probably incorrect check proxy example: https://github.com/eclipse-tractusx/tutorial-resources/blob/main/icc-irs-challenges/proxy.js |
| index.html contains API Key | Remove API Key, it has to be part of the proxy config. |
| Nothing happens when I start a Job | Check that the base URL for the IRS API calls in your JavaScript is set to http://localhost:3000 and that the requests are not just the paths. |
| Mermaid does not render the Graph | Check that mermaid is initialized correctly:mermaid.init(undefined, document.querySelectorAll('.mermaid')); |
| Submodel details will not be shown | Check if the matching of the submodel and the nodeId is correct: irsResponse.submodels.find(sm => sm.payload.catenaXId === nodeId; |
¶ Phase 1 (Detail Information): IRS Integration and Initial Visualisation
- Create the Web Client
- Integrating IRS REST APIs
- Visualize the IRS JobReponse
¶ Expected Outcome:
- 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
¶ Acceptance Criteria:
- Develop a user interface (UI) for a web application.
- Integrate the IRS API within the web application. 2.1 https://irs-ic.a3fb75c369e540489a65.germanywestcentral.aksapp.io/api/swagger-ui/index.html
- API KEY:
EZzzwfWcwtMJGvqxivalUyMOQhjjTTvv - Register an IRS job with all required semantic models.
- Check the JobResponse for completion.
- Retrieve the IRS JobResponse.
- Visualize the JobResponse JSON in the UI.
¶ 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.serial_part:3.0.0#SerialPart",
"urn:samm:io.catenax.batch:3.0.0#Batch",
"urn:samm:io.catenax.just_in_sequence_part:3.0.0#JustInSequencePart"
],
"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 | Type |
|---|---|---|---|
| BPNL00000003AXS3 | urn:uuid:4509ea7c-c8d2-41a1-83ca-c214ee34af6c | Vehicle Electric | |
| BPNL00000003AXS3 | urn:uuid:f5271c29-cde6-4fcd-816b-70b189756fd5 | Vehicle Electric | |
| BPNL00000003AXS3 | rn:uuid:c177bb4e-3208-427e-b98c-fcc790e3eb35 | Vehicle Electric | |
| BPNL00000003AXS3 | urn:uuid:8dd4a70d-c72d-4dae-95d7-deee2c4d62b2 | Vehicle Electric | |
| BPNL00000003AXS3 | urn:uuid:2d4aba5d-53fd-4466-9b16-15e4fed6be15 | Vehicle Combustion | |
| BPNL00000003AXS3 | urn:uuid:f03c22d7-0157-49ce-bc73-b835818d85ea | Vehicle Combustion | |
| BPNL00000003AXS3 | urn:uuid:f9f43f3e-1692-4079-b3e0-7107ee0953df | Vehicle Combustion | |
| BPNL00000003AXS3 | urn:uuid:2c2497de-8b10-464c-aa41-8eaf9e6ccf8c | Vehicle Combustion |
Vehicle Electric
Vehicle → SerialPart
Battery → Batch
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
HV MODUL → JustInSequencePart
Vehicle Combustion
Vehicle → SerialPart
Door f-l → SerialPart
Door Key → JustInSequencePart
Chassis → SerialPart
Tires → SerialPart
ECU → SerialPart
Sensor → SerialPart
Engineering Plastics → Batch
¶ Request job response
Polling a job until job state is equals "COMPLETED" ( "job":"state": "COMPLETED")
GET /irs/jobs/{id}?returnUncompletedJob=true
¶ Request job response
Polling job for a given id until job state is equals "COMPLETED".
{
"job"{
...,
"state": "COMPLETED",
...
}¶ Description of JobResponse objects
¶
| 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). |
¶ Structure of job response
¶ Relationship between shells (twins):
Relationship object in relationships related to shell object in shells via catenaXId → globalAssetId
¶ Relationship between shells(twins) and submodels:
Relationship object in relationships related to submodel object in submodels via catenaXId → catenaXId.
¶ Phase 2 (Detail Information):
. Visualize the part chain inside IRS JobResponse built according to the Industry Core Standard.
¶ Expected Outcome :
Graph-view showcasing AssetAdministrationShells (AAS) and their relations, leveraging the semantic aspect SingleLevelBOMAsBuilt (SLBAB) to implement Parent-Child connections, where SLBAB is registered on the parent side to establish a downward relationship between parent and child components.
¶ Acceptance Criteria:
Node Representation
- Asset Administration Shells (AAS) are displayed as nodes in the graph.
- SingleLevelBOMAsBuilt (SLBAB) are displayed as edges in the graph.
Mandatory and Optional Fields for AAS Nodes
- Mandatory Fields:
globalAssetId: urn:uuid4manufacturerId: BPNLmanufacturerPartId: StringdigitalTwinType: String
- Optional Fields:
customerPartId: String
Edge Representation for SingleLevelBOMAsBuilt
- Mandatory Fields:
catenaXIdchildItems|catenaXId : urn:uuid4childItems|businessPartner : BPNL
¶
Phase 3 (Detail Information):
Visualizing aspect data linked to digital twins according to the industry core standards.
¶ Expected Outcome :
Graph-view showcasing AssetAdministrationShells (AAS) and their relations, leveraging the semantic aspect SingleLevelBOMAsBuilt (SLBAB) to implement Parent-Child connections, where SLBAB is registered on the parent side to establish a downward relationship between parent and child components.
Graph-view showcasing semantic models (SerialPart, Batch, JustInSequencePart)
¶ Acceptance Criteria:
Node Representation
- Asset Administration Shells (AAS) are displayed as nodes in the graph.
- SingleLevelBOMAsBuilt (SLBAB) are displayed as edges in the graph.
- Semantic Models Attached to AAS. AAS are enriched with additional semantic models based on their semantic type.
¶ In case Semantic Model ‘SerialPart' is attached to AAS :
- Mandatory Fields:
globalAssetId: urn:uuid:*manufacturerId: BPNLmanufacturerPartId: StringdigitalTwinType: StringpartInstanceId: StringintrinsicId: String
- Optional Fields:
customerPartId: Stringvan: String
¶ In case Semantic Model ‘Batch’ is attached to AAS :
- Mandatory Fields:
globalAssetId: urn:uuid:*manufacturerId: BPNLmanufacturerPartId: StringdigitalTwinType: StringbatchId: StringintrinsicId: String
- Optional Fields:
customerPartId: String
¶ In case Semantic Model ‘JustInSequencePart' is attached to AAS :
- Mandatory Fields:
globalAssetId: urn:uuid:*manufacturerId: BPNLmanufacturerPartId: StringdigitalTwinType: StringjisNumber: StringjisCallDate: DateintrinsicId: String
- Optional Fields:
customerPartId: StringparentOrderNumber: String
Fields in Semantic Models
¶ SerialPart (3.0.0):
manufacturingInformation:datemanufacturingInformation:countrynameAtManufacturernameAtCustomercustomerPartId
¶ Batch (3.0.0):
manufacturingInformation:datemanufacturingInformation:countrynameAtManufacturernameAtCustomercustomerPartId
¶ JustInSequencePart (3.0.0):
manufacturingInformation:datemanufacturingInformation:countrypartTypeInformation:manufacturerPartIdpartTypeInformation:nameAtManufacturer
¶ Outcome Sample
¶ Visualization of IRS Result
¶ IRS Job Results
¶ Challenge bonus tasks
| Bonus Task | Name | Description | |
| 1 | Name Node AAS | Name Node AAS with value of attribute “idShort” in Graph. |
 |
| 2 | Visualize manufacturing country via country flag |
Semantic models SerialPart, Batch contains attribute
|
 |
| 3 | Visualize manufacturing date via date format | Semantic models SerialPart, Batch contains attribute manufacturingInformation[1].datethis contains an UTC timestamp which should be shown in local time. |
|
| 4 | Use different nodes shapes for aas nodes and submodel nodes | Use node with round edges for aas. Use node with stadium-shaped node for submodels. |
¶ Glossary
| Abbreviation | Description | Reference |
| AAS | AssetAdministrationShell | AAS |
| SLBAB | SingleLevelBOMAsBuilt | SLBAB |