Skip to content

Commit 9a45918

Browse files
FaheemBhattifaheem
FaheemBhatti
and
faheem
authored
Feature impr/digital twin registry (#859)
* DTR initial commit * feature printer addition * custom documentation * adding SPDX-License-Identifier to the new added files * review suggested changes from Arno * UT's * feature aas digital twin registry * feature digital twin registry * log level from TRACE --> INFO * merge failure resolve * update parent pom to revert not needed changes * refactoring acc to the requested changes * docs updation * revert cosmetic changes on parent pom * remove db details * remove circular reference * removing circular ref * cosmetic changes revert * improve log statement in the DiscoveryIntegrationAasRegistrytest class * exclusion optimization and discovery behaviour adjust acc to actual * resolve test failures in the discovery feature integration, add discovery feature in aas registry variations * dtr module to InMemory from MongoDB to test workflows * updating the registry poms * pom updatin * pom updation * removing potential dependecies causing bean pollution * test properties for the aas registry digital twin feature --------- Co-authored-by: faheem <faheem.bhatti@smart-systems-hub.de>
1 parent 3ccf990 commit 9a45918

28 files changed

Lines changed: 1900 additions & 6 deletions

File tree

‎.github/workflows/basyx_test.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -736,6 +736,39 @@ jobs:
736736
exit 1;
737737
fi
738738
739+
test-basyx-aasdigitaltwinregistry:
740+
runs-on: ubuntu-latest
741+
name: AAS Digital Twin Registry Service Test
742+
steps:
743+
- uses: actions/checkout@v4
744+
745+
- name: Set up JDK 17
746+
uses: actions/setup-java@v4
747+
with:
748+
java-version: '17'
749+
distribution: 'adopt'
750+
cache: maven
751+
752+
- name: Build BaSyx
753+
run: mvn clean install ${MVN_ARGS_BUILD_BASYX}
754+
755+
- name: Test AAS Digital Twin Registry Service
756+
run: mvn test -f "basyx.aasdigitaltwinregistry/pom.xml"
757+
758+
- name: Fail if no Surefire/Failsafe reports found
759+
run: |
760+
if ! find . -type f \( -path "*/target/surefire-reports/*.xml" -o -path "*/target/failsafe-reports/*.xml" \) | grep -q .; then
761+
echo "No Surefire or Failsafe test reports found. Failing CI.";
762+
exit 1;
763+
fi
764+
765+
- name: Fail if no Surefire/Failsafe reports found
766+
run: |
767+
if ! find . -type f \( -path "*/target/surefire-reports/*.xml" -o -path "*/target/failsafe-reports/*.xml" \) | grep -q .; then
768+
echo "No Surefire or Failsafe test reports found. Failing CI.";
769+
exit 1;
770+
fi
771+
739772
- name: Stop environment
740773
if: always()
741774
run: docker compose --project-directory ./ci down

‎.github/workflows/docker-milestone-release.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ jobs:
4343
path: basyx.submodelregistry/basyx.submodelregistry-service-release-log-mem/src/main/docker
4444
- name: submodel-registry-log-mongodb
4545
path: basyx.submodelregistry/basyx.submodelregistry-service-release-log-mongodb/src/main/docker
46+
- name: digitaltwinregistry
47+
path: basyx.aasdigitaltwinregistry/basyx.digitaltwinregistry.component
4648

4749
steps:
4850
- name: Checkout Code

‎.github/workflows/docker-snapshot-release.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ jobs:
5959
path: basyx.submodelregistry/basyx.submodelregistry-service-release-log-mem/src/main/docker
6060
- name: submodel-registry-log-mongodb
6161
path: basyx.submodelregistry/basyx.submodelregistry-service-release-log-mongodb/src/main/docker
62+
- name: digitaltwinregistry
63+
path: basyx.aasdigitaltwinregistry/basyx.digitaltwinregistry.component
6264

6365
steps:
6466
- name: Checkout Code

‎basyx.aasdigitaltwinregistry/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
2+
3+
# BaSyx Digital Twin Registry
4+
5+
## Overview
6+
The **Digital Twin Registry** serves as a combined module that merges the capabilities of `AASRegistry` and `AASDiscovery`.
7+
When a client calls the `/shell-description` endpoint, the module dynamically constructs both an `AssetAdministrationShellDescriptor` and an `aasDiscoveryDocumentEntity`.
8+
9+
This dual-output ensures that the asset shell becomes immediately discoverable and accessible, blending registry and discovery functionalities in a seamless operation.
10+
11+
---
12+
13+
## How It Works
14+
15+
- **Endpoint Integration**
16+
17+
A single REST endpoint (`/shell-description`) triggers the generation of:
18+
- An **AAS Descriptor**, representing the asset's metadata and management interface.
19+
- A **Discovery Document**, enabling other components to locate or resolve the AAS.
20+
21+
- **Unified Workflow**
22+
By combining `AASRegistry` and `AASDiscovery`, the module streamlines the typical sequential two-step — *discover then retrieve* — into a single integrated operation.
23+
24+
---
25+
26+
## Module Structure in the BaSyx SDK
27+
28+
- **New Module Introduction**
29+
Within the main BaSyx SDK, a new module — `digitaltwinregistry` — has been introduced.
30+
It follows the **decorator pattern**, meaning it wraps around existing functionality to extend behavior without modifying original code.
31+
32+
- **Delegate-Based Design**
33+
At its core, the module implements or creates a **delegate** for the `ShellDescriptorsApiDelegate` interface.
34+
This delegate intercepts API calls (particularly related to shell descriptions) and injects the registry-and-discovery logic — making the module effectively pluggable and maintainable.
35+
36+
---
37+
38+
## Summary
39+
40+
In essence, the **Digital Twin Registry module**:
41+
42+
- Combines **registry** and **discovery** into a unified action via `/shell-description`.
43+
- Is implemented as a **decorator delegate** (`ShellDescriptorsApiDelegate`), making it both modular and maintainable.
44+
- Seamlessly integrates with existing BaSyx storage options and aligns with broader architectural goals, such as centralized registries, tagging, and scalable discovery.
45+
46+
## Environment
47+
This document describes the environment variables used to configure the BaSyx Digital Twin Registry application. The application supports multiple profiles with different storage backends.
48+
49+
---
50+
51+
## Configuration Files
52+
The application uses three YAML configuration files:
53+
54+
- `application.yml` - Base configuration
55+
- `application-InMemory.yml` - In-memory storage profile
56+
- `application-MongoDB.yml` - MongoDB storage profile
57+
58+
---
59+
60+
## Environment Variables
61+
62+
### Base Configuration (`application.yml`)
63+
64+
| Environment Variable | Default Value | Description |
65+
|-----------------------|---------------|-------------|
66+
| `SPRING_PROFILE` | MongoDB | Active Spring profile (`InMemory` or `MongoDB`) |
67+
| `LOGGING_LEVEL` | INFO | Logging level for root and BaSyx components |
68+
69+
---
70+
71+
### Server Configuration
72+
73+
| Property | Default Value | Description |
74+
|----------------|---------------|-------------|
75+
| `server.port` | 8081 | HTTP server port |
76+
77+
---
78+
79+
### CORS Configuration
80+
81+
| Property | Value | Description |
82+
|--------------------------------|-----------------------------------------------------|-------------|
83+
| `basyx.cors.allowed-methods` | GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD | Allowed HTTP methods |
84+
| `basyx.cors.allowed-origins` | * | Allowed origins (CORS) |
85+
86+
---
87+
88+
### Management Endpoints
89+
90+
| Property | Value | Description |
91+
|------------------------------------------|------------------------------|-------------|
92+
| `management.endpoints.web.exposure.include` | health,metrics,mappings | Exposed actuator endpoints |
93+
94+
---
95+
96+
### SpringDoc/Swagger Configuration
97+
98+
| Property | Value | Description |
99+
|-----------------------------------|--------------------|-------------|
100+
| `springdoc.api-docs.enabled` | true | Enable API documentation |
101+
| `springdoc.swagger-ui.enabled` | true | Enable Swagger UI |
102+
| `springdoc.swagger-ui.path` | /swagger-ui.html | Swagger UI path |
103+
| `springdoc.swagger-ui.csrf.enabled` | false | Disable CSRF protection for Swagger |
104+
105+
---
106+
107+
## InMemory Profile Configuration
108+
109+
**Profile Name:** `InMemory`
110+
111+
### Environment Variables
112+
_No additional environment variables required for InMemory profile._
113+
114+
### Configuration Properties
115+
116+
| Property | Value | Description |
117+
|---------------------|------------|-------------|
118+
| `basyx.backend` | InMemory | Use in-memory storage backend |
119+
| `registry.type` | InMemory | Registry type |
120+
| `registry.discovery.enabled` | true | Enable discovery service |
121+
122+
### Auto-configuration Exclusions
123+
The InMemory profile excludes MongoDB auto-configuration:
124+
125+
- `org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration`
126+
- `org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration`
127+
128+
---
129+
130+
## MongoDB Profile Configuration
131+
132+
**Profile Name:** `MongoDB`
133+
134+
### Environment Variables
135+
136+
| Environment Variable | Default Value | Description |
137+
|---------------------------|-----------------------------------------|-------------|
138+
| `AUTHENTICATION_DATABASE` | aasregistry | MongoDB authentication database name |
139+
| `DATABASE_HOST` | localhost | MongoDB host address |
140+
| `DATABASE_PORT` | localhost | MongoDB port (**Note:** should be a numeric port) |
141+
| `DATABASE_USERNAME` | smartsystemhub | MongoDB username |
142+
| `DATABASE_PASSWORD` | smartsystemshubdatabaseforfactoryX | MongoDB password |
143+
144+
### Configuration Properties
145+
146+
| Property | Value | Description |
147+
|---------------------|---------|-------------|
148+
| `basyx.backend` | MongoDB | Use MongoDB storage backend |
149+
| `registry.type` | MongoDB | Registry type |
150+
| `registry.discovery.enabled` | true | Enable discovery service |
151+
| `basyx.aasdiscoveryservice.mongodb.collectionName` | aasregistry | MongoDB collection name |

‎basyx.aasdigitaltwinregistry/basyx.digitaltwinregistry.component/Dockerfile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
FROM eclipse-temurin:17
2+
USER nobody
3+
WORKDIR /application
4+
ARG JAVA_OPTS
5+
ENV JAVA_OPTS=$JAVA_OPTS
6+
ARG JAR_FILE=target/*.jar
7+
COPY ${JAR_FILE} basyxExecutable.jar
8+
9+
COPY src/main/resources/application.yml application.yml
10+
COPY src/main/resources/application-MongoDB.yml application-MongoDB.yml
11+
COPY src/main/resources/application-InMemory.yml application-InMemory.yml
12+
13+
ARG PORT=8081
14+
ENV SERVER_PORT=${PORT}
15+
ARG CONTEXT_PATH=/
16+
ENV SERVER_SERVLET_CONTEXT_PATH=${CONTEXT_PATH}
17+
EXPOSE ${SERVER_PORT}
18+
19+
HEALTHCHECK --interval=30s --timeout=3s --retries=3 --start-period=15s \
20+
CMD curl --fail http://localhost:${SERVER_PORT}${SERVER_SERVLET_CONTEXT_PATH%/}/actuator/health || exit 1
21+
22+
ENTRYPOINT exec java $JAVA_OPTS -Djava.security.egd=file:/dev/./urandom -jar basyxExecutable.jar

0 commit comments

Comments
 (0)