Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(verification): added readme guide and insomnia collection #465

Merged
merged 3 commits into from
Dec 5, 2024
Merged

chore(verification): added readme guide and insomnia collection #465

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1ab26a6
chore(verification): added readme guide and insomnia collection
saudkhan116 Dec 4, 2024
52758de
chore(irs): updated irs guide
saudkhan116 Dec 4, 2024
44440c3
chore: updated IP checks
matbmoser Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion DEPENDENCIES_BACKEND
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ maven/mavencentral/jakarta.validation/jakarta.validation-api/3.0.2, Apache-2.0,
maven/mavencentral/jakarta.xml.bind/jakarta.xml.bind-api/4.0.2, BSD-3-Clause, approved, ee4j.jaxb
maven/mavencentral/net.minidev/accessors-smart/2.5.1, Apache-2.0, approved, clearlydefined
maven/mavencentral/net.minidev/json-smart/2.5.1, Apache-2.0, approved, clearlydefined
maven/mavencentral/org.apache.commons/commons-collections4/4.4, Apache-2.0, approved, clearlydefined
maven/mavencentral/org.apache.commons/commons-collections4/4.4, Apache-2.0, approved, #17660
maven/mavencentral/org.apache.commons/commons-lang3/3.14.0, Apache-2.0, approved, #11677
maven/mavencentral/org.apache.commons/commons-text/1.11.0, Apache-2.0, approved, clearlydefined
maven/mavencentral/org.apache.logging.log4j/log4j-api/2.23.1, Apache-2.0, approved, #13368
Expand Down
211 changes: 146 additions & 65 deletions dpp-tutorial/irs-drill-down.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,23 @@
<!--
Tractus-X - Digital Product Passport Application

Copyright (c) 2022, 2024 BMW AG, Henkel AG & Co. KGaA
Copyright (c) 2023, 2024 CGI Deutschland B.V. & Co. KG
Copyright (c) 2022, 2024 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under the
terms of the Apache License, Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the
License for the specific language govern in permissions and limitations
under the License.

SPDX-License-Identifier: Apache-2.0
<!--
#######################################################################

Tractus-X - Digital Product Pass Application

Copyright (c) 2024 BMW AG
Copyright (c) 2024 CGI Deutschland B.V. & Co. KG
Copyright (c) 2024 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This work is made available under the terms of the
Creative Commons Attribution 4.0 International (CC-BY-4.0) license,
which is available at
https://creativecommons.org/licenses/by/4.0/legalcode.

SPDX-License-Identifier: CC-BY-4.0

#######################################################################
-->

# Introduction
Expand Down Expand Up @@ -240,9 +238,9 @@ curl --location '<DATA_SERVICE_URL>/<SerialPartID>' \
--header 'Content-Type: application/json' \
```

## 6° Attach BOMAsBuilt to Existing Digital Twin
## 6° Add BOMAsBuilt and SerialPart to Existing Digital Twin

* Get existing digital Twin by Base64 encoded digital twin Id
* To get the existing digital twin, get your part Id from the given paper and encode it into Base64.

The digital twin registered can be checked/verified from the following command:

Expand Down Expand Up @@ -271,7 +269,6 @@ Example JSON response:
"id": "urn:uuid:a530baad-77ad-4ffc-a925-f3a207839791",
"specificAssetIds": [
{
"supplementalSemanticIds": [],
"name": "manufacturerPartId",
"value": "MPI7654",
"externalSubjectId": {
Expand All @@ -286,68 +283,152 @@ Example JSON response:
}
],
"submodelDescriptors": [
{
"endpoints": [
{ ... }
]
}
{
"endpoints": [
{
"interface": "SUBMODEL-3.0",
"protocolInformation": {
...
}
}
],
"idShort": "digitalProductPass",
"id": "urn:uuid:d2e47115-c430-4145-bbde-1c743804a379",
...
}
]
}
```

Copy the actual json response and paste it into the notepad editor. You will need the values later.
- Search for the `submodelDescriptors` array. We need to add more elements to the submodelDescriptors array.

### Update Digital Twin
- Copy your response and add the following json content into the submodelDescriptors array:

```json
{
"endpoints": [
{
"interface": "SUBMODEL-3.0",
"protocolInformation": {
"href": "<EDC_DATAPLANE_URL>/api/public/<BOMAsBuiltID>",
"endpointProtocol": "HTTP",
"endpointProtocolVersion": ["1.1"],
"subprotocol": "DSP",
"subprotocolBody": "id=urn:uuid:0c3d2db0-e5c6-27f9-5875-15a9a00e7a27;dspEndpoint=<EDC_CONTROLPLANE_URL>",
"subprotocolBodyEncoding": "plain",
"securityAttributes": [
{
"type": "NONE",
"key": "NONE",
"value": "NONE"
}
]
}
}
],
"idShort": "singleLevelBomAsBuilt",
"id": "<BOMAsBuiltID>",
"semanticId": {
"type": "ExternalReference",
"keys": [
{
"type": "Submodel",
"value": "urn:samm:io.catenax.single_level_bom_as_built:3.0.0#SingleLevelBomAsBuilt"
}
]
},
"description": [
{
"language": "en",
"text": "DPP singleLevelBOMAsBuilt Submodel"
}
],
"displayName": []
},
{
"endpoints": [
{
"interface": "SUBMODEL-3.0",
"protocolInformation": {
"href": "<EDC_DATAPLANE_URL>/api/public/<serialPartID>",
"endpointProtocol": "HTTP",
"endpointProtocolVersion": ["1.1"],
"subprotocol": "DSP",
"subprotocolBody": "id=urn:uuid:0c3d2db0-e5c6-27f9-5875-15a9a00e7a27;dspEndpoint=<EDC_CONTROLPLANE_URL>",
"subprotocolBodyEncoding": "plain",
"securityAttributes": [
{
"type": "NONE",
"key": "NONE",
"value": "NONE"
}
]
}
}
],
"idShort": "serialPart",
"id": "<serialPartID>",
"semanticId": {
"type": "ExternalReference",
"keys": [
{
"type": "Submodel",
"value": "urn:samm:io.catenax.serial_part:3.0.0#SerialPart"
}
]
},
"description": [
{
"language": "en",
"text": "DPP serial part Submodel"
}
],
"displayName": []
}
```

Attach the following **SingleLevelBOMAsBuilt** and **SerialPart** aspects to the existing Digital Twin object that you retrieved and substitute the corresponding placeholders **<BOMAsBuiltID<BOMAsBuiltID>>** and **<SerialPart<SerialPart>>** with their Ids generated in [step 1](#1-generate-the-ids).
- Substitute the corresponding placeholders **<BOMAsBuiltID<BOMAsBuiltID>>** and **<SerialPart<SerialPart>>** with their Ids generated in [step 1](#1-generate-the-ids).

Example to find the placeholders:

1 - Get access to the file [example-dt-irs](./resources/digital-twins/example-dt-irs.json)
> [!IMPORTANT]
> `<EDC_CONTROLLANE_URL>` and `<EDC_DATAPLANE_URL>` are given in a paper

2 - Get the placeholders from the below table and search with CTRL + F in [example-dt-irs](./resources/digital-twins/example-dt-irs.json):
> [!CAUTION]
> Please make sure that you substitute all the placeholders with their values

3 - Substitute the following placeholders with their values. The values you will get them from the existing digital twin object that was retrieved.
- Search for the `supplementalSemanticId` keyword (if any) and remove that line.

- Save your changes to a json file.

| Placeholder | Path |
|------------------------- |-----------------------------------------------------------------|
| <digitalTwinId<digitalTwinId>> | globalAssetId |
| | id |
| <PART_NAME> | idShort |
| <YOUR PART INSTANCE ID<y>> | specificAssetIds[1].value |
| <EDC_DATAPLANE_URL> | submodelDescriptors[0].endpoints[0].protocolInformation.href |
| | submodelDescriptors[1].endpoints[0].protocolInformation.href |
| | submodelDescriptors[2].endpoints[0].protocolInformation.href |
| <digitalTwinSubmodelId<y>> | submodelDescriptors[0].endpoints[0].protocolInformation.href |
| | submodelDescriptors[0].id |
| <EDC_CONTROLPLANE_URL> | submodelDescriptors[0].endpoints[0].subprotocolBody |
| | submodelDescriptors[1].endpoints[0].subprotocolBody |
| | submodelDescriptors[2].endpoints[0].subprotocolBody |
| <BOMAsBuiltID<BOMAsBuiltID>> | submodelDescriptors[1].endpoints[0].protocolInformation.href |
| | submodelDescriptors[1].id |
| <serialPartID<serialPartID>> | submodelDescriptors[2].endpoints[0].protocolInformation.href |
| | submodelDescriptors[2].id |

> [!TIP]
> The table shows number of occurences of a specific property, for example <digitalTwinId<y>> has two occurences: `globalAssetId` and `id`
### Update Digital Twin with BOMAsBuilt and SerialPart Submodels

Update the digital twin submodel using the following command:

> [!CAUTION]
> Please make sure that you substitute all the placeholders with their values from the above table
> PUT /shell-descriptors/<DIGITAL_TWIN_ID_BASE64_ENCODED>

> Please only use your assigned UUID from [here](./resources/test-data/carParts.json) that matches the UUID on the given paper
*Windows*
<details>
<summary>Click to see the Windows command</summary>

4 - Save your modified digital twin in json format.
```bash
curl.exe -v -X PUT "<DIGITAL_TWIN_REGISTRY_URL>/shell-descriptors/<DIGITAL_TWIN_ID_BASE64_ENCODED>" `
-H "Content-Type: application/json"
--data-binary "@<YOUR_JSON_FILE>.json"`"
```

Now, you can update the modified digital twin object using the following command:
</details>

> PUT /shell-descriptors/<DIGITAL_TWIN_ID_BASE64_ENCODED>
*Mac & Linux*
<details>
<summary>Click here to see the Mac & Linux command</summary>

```bash
curl --location --request PUT '<DIGITAL_TWIN_REGISTRY_URL>/shell-descriptors/<DIGITAL_TWIN_ID_BASE64_ENCODED>' \
--header 'Content-Type: application/json' --data '@resources/<YOUR_DT_JSON>.json'
curl --location '<DIGITAL_TWIN_REGISTRY_URL>/shell-descriptors/<DIGITAL_TWIN_ID_BASE64_ENCODED>' \
--header 'Content-Type: application/json' \
--data "@<YOUR_JSON_FILE>.json"
```
</details>


Congratulations, you have successfully attached BOMAsBuilt relationships and serial part to the existing Digital Twin object.
Loading