- **Mnestix Browser on port 3000 - http://localhost:3000** -
- -- **docker-compose/compose.frontend.yml** - runs Mnestix Browser with a Basyx environment (AAS-Environment with MongoDB, - Discovery Service, AAS/Submodel Registry) but without the Mnestix-API.
- **Mnestix Browser on port 3000 - http://localhost:3000** - -- **docker-compose/compose.dev.yml** - override file to run Mnestix Browser in a development environment. A development - image will be built if it is not found in the local Docker Image Cache.
- **Mnestix Browser on port 3000 - http://localhost:3000**
- **Mnestix Api on port 5064 - http://localhost:5064**
- **AAS Repo on port 8081 - http://localhost:8081/swagger-ui/index.html**
- -- **docker-compose/compose.test.yml** - override file used to configure and run end-to-end (E2E) tests using Cypress. - When this file is executed, it will start the necessary services for the application and execute the Cypress tests. - If any test fails, the results and logs will be saved in a designated directory for further analysis.
- -- **docker-compose/compose.azure_ad.yml** - override file to activate authentication using Azure Entra ID. - You will need to provide your own Authentication Endpoint. - Configuration can be found [here](#using-azure-entra-id).
- -- **docker-compose/compose.keycloak.yml** - override file to activate authentication using keycloak. - Configuration can be found [here](#keycloak-configuration).
- **keycloak admin page - http://localhost:8080** - -The files in the `docker-compose` directory -are [override compose files](https://docs.docker.com/compose/multiple-compose-files/merge/), which must be added with -the `-f
-The services are grouped into three [compose profiles](https://docs.docker.com/compose/profiles/): `basyx`, `backend` -and `frontend`. -They can be started together without defining `--profile` or separately by adding `--profile
](https://industrialdigitaltwin.org/wp-content/uploads/2023/07/2023-07-27_IDTA_Tutorial_V3.0-Specification-AAS-Part-2_API.pdf)\
-(
-Source: [IDTA](https://industrialdigitaltwin.org/wp-content/uploads/2023/07/2023-07-27_IDTA_Tutorial_V3.0-Specification-AAS-Part-2_API.pdf))
-
-A tutorial about the Discovery Service along with the registries can be
-found [on the IDTA website](https://industrialdigitaltwin.org/wp-content/uploads/2023/07/2023-07-27_IDTA_Tutorial_V3.0-Specification-AAS-Part-2_API.pdf).
-
-### How to connect Mnestix Browser to the different components
-
-#### Running Mnestix with its API
-
-There also exists the [Mnestix API](https://hub.docker.com/r/mnestix/mnestix-api), that provides different business
-comfort features.
-Here it is possible to set an API Key, for example, to secure your backend services like the repository or the discovery
-service.
-When running the [Mnestix API](https://hub.docker.com/r/mnestix/mnestix-api) you can change the paths to the different
-services like described in the [Mnestix API Documentation](https://hub.docker.com/r/mnestix/mnestix-api).
-For example (change `{{MNESTIX_BACKEND_API_URL}}` to the URL of the
-running [Mnestix API](https://hub.docker.com/r/mnestix/mnestix-api))
-
-```yaml
-DISCOVERY_API_URL: '{{MNESTIX_BACKEND_API_URL}}/discovery'
-AAS_REPO_API_URL: '{{MNESTIX_BACKEND_API_URL}}/repo'
-SUBMODEL_REPO_API_URL: '{{MNESTIX_BACKEND_API_URL}}/repo'
-MNESTIX_BACKEND_API_URL: '{{MNESTIX_BACKEND_API_URL}}'
-```
-
-#### Running Mnestix without its API
-
-This is the easiest configuration, for when you only want to visualize and browse through AAS.
-If you choose to run the Mnestix Browser without the Mnestix API, the Feature Flags `AUTHENTICATION_FEATURE_FLAG`
-and `AAS_LIST_FEATURE_FLAG` will be overwritten to `false` as these Features use the functionality of the API.
-The other environment variables should be configured [as described](#frontend-configuration). If you want to run Mnestix
-Browser with an Basyx environment you can simply use the compose.frontend file which is
-described [here](#Docker-Compose-files).
-
-#### How to configure the BaSyx AAS Repository
-
-We recommend the usage of Mnestix together with
-the [BaSyx AAS Repository](https://github.com/eclipse-basyx/basyx-java-server-sdk).
-This component stores all the different AAS (type 2), it is recommended to configure it to use a database for
-persistence.
-We recommend to set the following environment variables (replace `{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}` with the
-corresponding values):
-
-```yaml
-# Allow to upload bigger AASX files
-SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE: 100000KB
-SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE: 100000KB
-# Allow mnestix frontend and backend to call basyx
-BASYX_CORS_ALLOWED-ORIGINS: '{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}'
-BASYX_CORS_ALLOWED-METHODS: GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD
-```
-
-If you are using the Mnestix API see [here](#running-mnestix-with-its-api) on how to set the Frontend Flags.
-If you are using only the Mnestix Browser just set the environment variables `AAS_REPO_API_URL` and
-`SUBMODEL_REPO_API_URL` accordingly.
-
-#### How to configure the BaSyx Discovery Service
-
-We recommend the usage of Mnestix together with
-the [BaSyx AAS Discovery Service](https://github.com/eclipse-basyx/basyx-java-server-sdk/tree/main/basyx.aasdiscoveryservice).
-This component links Asset IDs to AAS IDs. It is recommended to configure it to use a database for persistence.
-We recommend to set the following environment variables (replace `{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}` with the
-corresponding values):
-
-```yaml
-# Allow mnestix frontend and backend to call discovery service
-BASYX_CORS_ALLOWED-ORIGINS: '{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}'
-BASYX_CORS_ALLOWED-METHODS: GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD
-```
-
-If you are using the Mnestix API see [here](#running-mnestix-with-its-api) on how to set the Frontend Flags.
-If you are using only the Mnestix Browser just set the environment variable `DISCOVERY_API_URL` accordingly.
-
-#### Technical Information - Discovery Service
-
-The functions that are described in
-the [Specification AAS - Part 2: API](https://industrialdigitaltwin.org/wp-content/uploads/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf)
-were implemented in the [`discoveryServiceApi.ts`](src/lib/api/discovery-service-api/discoveryServiceApi.ts).
-They make the respective `GET`, `POST` and `DELETE` requests to the specified `DISCOVERY_API_URL`.
-Two additional functions were added that simplify the usage of the Discovery Service by just requiring the globalAssetId
-and no additional AssetLinks.
-
-These functions are `LinkAasIdAndAssetId(aasId: string, assetId: string)` and `GetAasIdsByAssetId(assetId: string)`.
-The return of all functions is the response from the Discovery Service parsed as an object.
-So they can be used like in the example below:
-
-```typescript
-await LinkAasIdAndAssetId(aasId, assetId);
-const foundAasIds = (await discoveryServiceClient.GetAasIdsByAssetId(assetId)).result;
-```
-
-#### How to configure the BaSyx AAS Registry Service
-
-The AAS Registry Service is designed to provide descriptors for Asset Administration Shells (AAS),
-including endpoints to various repositories that may be stored elsewhere.
-This architecture ensures support for multiple repositories, provided they are registered in the designated AAS
-registry.
-
-When an AAS for the specified AAS-Id is found, it is displayed in the detail view. If the AAS is not found,
-the service will search in the local repository for the requested information.
-
-If the discovery service is configured, it will initially identify the relevant AAS-ID for the searched Asset ID before
-querying the Registry Service.
-Configuration of the Registry Service is optional. If the AAS Registry Service is not configured, the search will
-default to the local repository.
-
-To configure the AAS registry, please provide the URL in the Frontend Configuration variables.
-
-```yaml
-REGISTRY_API_URL: '{{REGISTRY-SERVICE-URL}}'
-```
-
-By setting the REGISTRY_API_URL, you enable the AAS Registry Service, ensuring efficient retrieval of AAS descriptors.
-
-#### How to configure the BaSyx Submodel Registry Service
-
-The Submodel Registry feature provides an optional configuration that allows you to manage and resolve submodels
-efficiently.
-When the Submodel Registry is configured, any reference to a submodel will first check if the submodel is available in
-the specified registry endpoint.
-If the submodel is found in the registry, it will be fetched from there. If the submodel is not found in the registry,
-the system will then check the local repository for the submodel.
-
-Configuring the Submodel Registry is optional. If not configured, all submodel references will default to being resolved
-from the local repository only.
-
-To configure the Submodel registry, please provide the URL in the Frontend Configuration variables.
-
-```yaml
-SUBMODEL_REGISTRY_API_URL: '{{SUBMODEL_REGISTRY_API_URL}}'
-```
-
-By setting the SUBMODEL_REGISTRY_API_URL, you enable the Submodel Registry Service, ensuring efficient retrieval of
-Submodel descriptors.
-
-#### Technical Information - Registry Service
-
-The functions that are described in
-the [Specification AAS - Part 2: API](https://industrialdigitaltwin.org/wp-content/uploads/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf)
-were implemented in the [`registryServiceApi.ts`](src/lib/api/registry-service-api/registryServiceApi.ts).
-They make the respective `GET`, `POST` and `DELETE` requests to the specified `REGISTRY_API_URL`.
-
-### Different Mnestix Configurations
-
-There are multiple scenarios possible on how to deploy the Mnestix Browser with different configurations.
-In the following, it is described, what scenarios were thought of and how to configure them
-
-#### I want to only view AAS
-
-If you just want to view AAS and integrate it into your existing environment, you can run only the `mnestix-viewer`
-without its API.
-See [Running Mnestix without its API](#Running-Mnestix-without-its-API).
-
-#### I want to use more advanced features
-
-There are also some more advanced features one might want to use.
-For this you need to enable the Mnestix API, see [here](#running-mnestix-with-its-api).
-It enables you to secure all `POST/PATCH/DELETE`-Request with an API-Key.
-The API-Key needs to be sent within the Header `ApiKey` to make those requests.
-Normal `GET/FETCH`-Requests are not affected by this.
-
-When using it is also possible to restrict some functions that you possibly don't want to be accessible.
-For example, it is possible to restrict the access to the `/shells` endpoint of the AAS repository by setting the
-backend environment variable `Features__AllowRetrievingAllShellsAndSubmodels: false`.
-Remember that this also means that the functionality to list all AAS won't work anymore in the Mnestix Browser, so
-disable this functionality with the environment variable `AAS_LIST_FEATURE_FLAG: false`.
-
-#### AAS List V2 Feature Details
-
-The `AAS_LIST_V2_FEATURE_FLAG` is a feature flag introduced as part of a preview release.
-It enables access to an updated list implementation that operates independently of the Mnestix API.
-
-This flag is currently disabled by default (false) and is available only in preview.
-It is not yet recommended for production environments.
-
-To enable the feature for testing or preview purposes, set the flag to true in your configuration.
-
-#### AzureAD Service
-
-One can also add an AzureAD Service to give people deeper access, this enables the "Login" Button in the Mnestix
-Browser.
-After logging in, users have access to even more functionality.
-To see how to connect to an Azure Tenant and enable the login functionality see
-the [official Mnestix API documentation](https://hub.docker.com/r/mnestix/mnestix-api).
-
-#### I want to create multiple AAS
-
-This option builds upon the advanced features described in
-the [previous section](#i-want-to-use-more-advanced-features).
-After logging in it is possible to configure the ID Generation Functionality of the backend.
-Here it is possible to automatically generate AAS using only a short ID of the Asset.
-How the AAS Creator in conjunction with the ID Generations Functionality works can be seen in
-the [official Mnestix API documentation](https://hub.docker.com/r/mnestix/mnestix-api).
-
-One can also use the Template Builder with the Data Ingest Endpoint to send arbitrary JSON files to the API and
-automatically add them to a specified AAS.
-This enables easy integration into existing ETL processes.
-How exactly this works can be seen in
-the [official Mnestix API documentation](https://hub.docker.com/r/mnestix/mnestix-api).
-
-Below you'll find a small overview on how the components interact with each other:
-
-
-## Maintaining
-
-### Setting up VSCode
-
-#### Extensions
-
-See `.vscode/extensions.json` for a list of recommended extensions.
-VSCode will suggest to install them when opening the project.
-
-#### Settings
-
-See `.vscode/settings.json` for defined workspace settings.
-
-### Setting up Rider
-
-Check the configurations for Rider under `.idea/` folder
-
-### Installing and adding/removing frontend packages
-
-### Formatting & Linting
-
-We use Prettier and ESLint to keep our frontend code clean. Having a ESLint warning **will break the pipeline**. It's
-therefore always a good idea to run `yarn format` and `yarn lint` before you commit.
-
-#### Run prettier check
-
-```sh
-yarn prettier
-```
-
-#### Run prettier (be aware, this changes files!)
-
-```sh
-yarn format
-```
-
-#### Check your code for formatting issues
-
-```sh
-yarn lint
-```
-
-If you want specific files or folders to be excluded from linting (e.g. generated files), you can add them
-to `.eslintignore` and `.prettierignore`
-
-### Cypress Testing
-
-We use Cypress for End-to-End-Testing. In order to navigate to the right folder and run Cypress you can use the
-following command. In order to use cypress testing the Mnestix Browser must be running.
-
-#### Open the cypress application
-
-```sh
-yarn test
-```
-
-#### Run cypress headless (runs all tests inside the integration folder)
-
-```sh
-yarn test:headless
-```
-
-Cypress will put videos and screenshots of the tests inside the cypress folder.
-
-In order to run your own E2E-Tests you can put your test files in `/cypress/e2e`.
-
-In the `fixtures` folder you can put data to use in your E2E-Tests as json files.
-
-If you have commands you want to use in multiple tests you can put them into the `commands.ts` file inside
-the `support` folder.
-Don't forget to write the method header of your custom commands inside the `e2e.ts` file as well. This way the IDE
-will stop marking your custom commands as wrong.
-
-### Reverse Proxy Configuration
-
-The YARP proxy route `/repo/shells` now limits resource and list returns to 104 elements due to the lack of pagination
-support.
-This change aims to prevent server overload and ensure smoother navigation through resource lists.
-
-## Keycloak Configuration
-
-> **Note:** Keycloak support is available starting from version 1.1.0 and above.
->
-> For Mnesitx API configuration details, please refer to the API documentation available
-> on [Docker Hub](https://hub.docker.com/r/mnestix/mnestix-api).
-
-### Setting Up Keycloak for Docker Development
-
-To start Mnestix along with Keycloak as the authorization server, use one of the following commands:
-
-```sh
-docker compose -f compose.yml -f docker-compose/compose.dev.yml -f docker-compose/compose.keycloak.yml up -d
-```
+## Quickstart
-or, alternatively:
+All you need to start your first Mnestix instance is the `compose.yml` (or clone the repository).
+In the root directory run the following command and open http://localhost:3000 in your web browser.
-```sh
-yarn docker:keycloak
+```shell
+docker compose up
```
-On the first startup, the Keycloak Docker image (`docker-compose/data/keycloak/Dockerfile`) will be built with an
-initializer configured for the BaSyx repository.
-This setup ensures that localhost can be resolved within the Docker network. Additionally, a preconfigured Keycloak
-realm (`docker-compose/data/keycloak/realm/BaSyx-realm.json`) will be imported,
-eliminating the need for any initial Keycloak configuration.
-
-The Keycloak Admin Console will be accessible at [http://localhost:8080/admin](http://localhost:8080/admin).
-
-For initial access, use the following temporary credentials:
-
-- **Username:** admin
-- **Password:** admin
-
-A test user is preconfigured with the following credentials allowing login to Mnestix Browser:
-
-- **Username:** test
-- **Password:** test
-
-### Configuration variables for keycloak setup
-
-`KEYCLOAK_LOCAL_URL`:
-
-- **Local Development:** This variable should be left empty when running Mnestix in a local browser environment.
-- **Docker Environment:** When running in a Docker environment, set this variable to `localhost:8080` to enable user
- credential input. In Docker, the token, user info, and other endpoints will function correctly within the Docker
- network.
-
-`NEXTAUTH_URL`: Required variable to configure redirect URL for NextAuth.
-
-`NEXTAUTH_SECRET`: Required variable used to encrypt the NextAuth.js JWT, and to hash email verification tokens.
-
-> ⚠️ **Important:** Ensure that you update any confidential variables from their default values before deploying to a
-> production environment.
-
-## Contributing
-
-Right now, we are building a community around Mnestix.
-If you are looking for a way to support us, you can start contributing to Mnestix right away.
-For this purpose, issues which are particularly suitable for a first contribution are labeled with the tag
-`good first issue`.
-If this is your first time contributing to an eclipse project, we recommend having a look at this
-guide: [Contributing to a Eclipse project](https://www.eclipse.org/contribute/).
-We would be more than happy to have you on board. If there is anything you want to know, feel free to contact
-us [mnestix@xitaso.com](mailto:mnestix@xitaso.com) or through our
-website [here](https://xitaso.com/kompetenzen/mnestix/#support).
+### If you want to further configure your mnestix instance, go to our [wiki](https://github.com/eclipse-mnestix/mnestix-browser/wiki).
From a59a9e7066410939d3766dc3844740fbf5ee8c74 Mon Sep 17 00:00:00 2001
From: NilsXitaso -
+ {props.isLoggedIn && (
+ <>
+
-
-
-
- {auth.isLoggedIn && (
- <>
- {getAuthName() &&
+ **Mnestix Browser on port 3000 - http://localhost:3000** + +- **docker-compose/compose.frontend.yml** - runs Mnestix Browser with a Basyx environment (AAS-Environment with MongoDB, Discovery Service, AAS/Submodel Registry) but without the Mnestix-API.
+ **Mnestix Browser on port 3000 - http://localhost:3000** + +- **docker-compose/compose.dev.yml** - override file to run Mnestix Browser in a development environment. A development + image will be built if it is not found in the local Docker Image Cache.
+ **Mnestix Browser on port 3000 - http://localhost:3000**
+ **Mnestix Api on port 5064 - http://localhost:5064**
+ **AAS Repo on port 8081 - http://localhost:8081/swagger-ui/index.html** + +- **docker-compose/compose.test.yml** - override file used to configure and run end-to-end (E2E) tests using Cypress. + When this file is executed, it will start the necessary services for the application and execute the Cypress tests. + If any test fails, the results and logs will be saved in a designated directory for further analysis. + +- **docker-compose/compose.azure_ad.yml** - override file to activate authentication using Azure Entra ID. + You will need to provide your own Authentication Endpoint. + Configuration can be found [here](https://github.com/eclipse-mnestix/mnestix-browser/wiki/Mnestix-Configuration-Settings#using-azure-entra-id). + +- **docker-compose/compose.keycloak.yml** - override file to activate authentication using keycloak. + Configuration can be found [here](keycloak-configuration).
+ **keycloak admin page - http://localhost:8080** + +The files in the `docker-compose` directory +are [override compose files](https://docs.docker.com/compose/multiple-compose-files/merge/), which must be added with +the `-f
+The services are grouped into three [compose profiles](https://docs.docker.com/compose/profiles/): `basyx`, `backend` +and `frontend`. +They can be started together without defining `--profile` or separately by adding `--profile
+ 
+
+ 
+
Mnestix
+ +[](https://xitaso.com/) +[](https://choosealicense.com/licenses/mit/) +[]() +[](https://xitaso.com/kompetenzen/mnestix/#support) + +### Welcome to the Mnestix Community! + +Mnestix Browser is an open source software designed to simplify the implementation of the Asset Administration Shell. +Together +with increasing contributions from users and developers, a growing community is working on further development under the +leadership of XITASO, a leading high-end software development company in the engineering industry. +Mnestix Browser is the perfect tool to demonstrate the power and potential of AAS (**Asset Administration Shells**) for +the +implementation of standardized digital twins. It opens the way for use cases such as the Digital Product Passport (DPP). + +You can find a demo [here](https://mnestix-prod.azurewebsites.net/). +Some screenshots can be found in the [screenshots folder](https://github.com/eclipse-mnestix/mnestix-browser/tree/main/screenshots). + +### **If you need support feel free to contact us through our website [here](https://xitaso.com/kompetenzen/mnestix/#support).** + +## Quickstart + +All you need to start your first Mnestix instance is the `compose.yml` (or clone the repository). +In the root directory run the following command and open http://localhost:3000 in your web browser. + +```shell +docker compose up +``` + +If you want to further configure your mnestix instance, read about [configuration](mnestix-configuration-settings). \ No newline at end of file diff --git a/wiki/How-to-Create-Custom-Submodel-Visualizations.md b/wiki/How-to-Create-Custom-Submodel-Visualizations.md new file mode 100644 index 00000000..9d109f83 --- /dev/null +++ b/wiki/How-to-Create-Custom-Submodel-Visualizations.md @@ -0,0 +1,219 @@ +One of Mnestix’ goals is to make it as easy as possible to visualize data. + +Out of the box, Mnestix offers a general visualization for submodels. Additionally, Mnestix offers a selection of tailored visualizations for standardized and not standardized submodels. +Those include for example visualizations for the Product Carbon Footprint submodel, the Hierarchical Structures submodel and the Time Series submodel. Additionally, Mnestix provides tailored visualizations for a selection of submodel elements, such as Address components, Document components and Entity components. + +In order to realize your own use cases, Mnestix provides a means to implement your own custom visualizations for submodels and submodel elements. +The following steps will explain how you can provide these visualizations. + + + +> [!TIP] +> For a starting point we provide an example submodel visualization at [SoftwareNameplate](https://github.com/eclipse-mnestix/mnestix-browser-example-submodel-visualizations). +> We encourage you to use this repository as a template for your own visualization. +> Throughout this guide are tips based on this submodel visualization. + + +# 1. Fork and Clone the Mnestix GitHub repository + +> [!NOTE] +> If you are not planning on contributing to Mnestix you can also skip the fork and directly clone the Mnestix repository. You will not be able to create branches and pull requests this way. + +## Fork Mnestix + +As for any other contribution to Mnestix, you will have to start by forking the GitHub repository. +You may fork either the [main branch](https://github.com/eclipse-mnestix/mnestix-browser) for stable release code or the [dev branch](https://github.com/eclipse-mnestix/mnestix-browser/tree/dev) for features which may still be under active development. +On the repository page you will then have the option to fork the code to your own account. + + + +## Clone Mnestix + +Clone the Mnestix code from the GitHub repository. +You may clone either the [main branch](https://github.com/eclipse-mnestix/mnestix-browser) for stable release code or the [dev branch](https://github.com/eclipse-mnestix/mnestix-browser/tree/dev) for features which may still be under active development. +If you have forked the Mnestix repository in the previous task, clone from your private repository. + +## Checking out Mnestix + +It is time to check if everything is set up correctly. +In this guide we assume you have installed docker and node correctly. +For a full guide on how to develop locally please consider our [Development guide](https://github.com/eclipse-mnestix/mnestix-browser/wiki/Getting-started-with-developing). +All commands shown should be executed in the root directory of Mnestix. + +First you need to install all required packages. +This can be done with `yarn install` and may take some time depending on your network connection. +If you have problems executing yarn, you might need to enable it using `corepack enable` first. + +Now you can start up all background services as docker containers. +We provide a few node scripts to ease the startup process. +During development `yarn docker:backend` will suffice in most cases. +For a full overview please check out the [compose guide](https://github.com/eclipse-mnestix/mnestix-browser/wiki/Docker-Compose-Files). + +To start the Mnestix browser you may use `yarn dev`. +To make sure debugging and hot-reloading works as expected you might instead use `yarn debug`. +You can now open `localhost:3000` in your internet browser and should see the Mnestix dashboard. +It might take a few extra seconds at the first time as node is building your project on the go. + +> [!Tip] +> You can try to find the Mnestix AAS in the list or search for it on the dashboard directly by entering its ID `https://vws.xitaso.com/aas/mnestix`. + +# 2. Create your React component + +We suggest to create a directory for your submodel visualization inside `src/user-plugins/submodels`. + +> [!TIP] +> To clone the software nameplate you may go into the `src/user-plugins/submodels/` directory and run `git clone https://github.com/eclipse-mnestix/mnestix-browser-example-submodel-visualizations.git`. +> You can browse the example AAS for the SoftwareNameplate with the ID `https://vws.xitaso.com/aas/mnestix` inside the Mnestix browser. + +You can find all currently existing submodel visualizations at the following path: `src/app/[locale]/viewer/_components/submodel`. +You might want to have a look at them for further examples. + +## Creating a visualization for a submodel + +After you created the sub-directory for your own visualization, you can create your `.tsx`-file and start developing the component. +Custom submodel visualizations use the input type `SubmodelVisualizationProps`, which contains the submodel data as `AAS-core-3` type. + +You can use this stump to develop a custom submodel visualization: + +```tsx +import { SubmodelVisualizationProps} from 'app/[locale]/viewer/_components/submodel/SubmodelVisualizationProps'; + +export default function CustomSubmodel({submodel}: SubmodelVisualizationProps){ + return ( +This is the custom visualization for submodel {submodel.idShort}
+ ); +} +``` + +> [!TIP] +> For now the custom visualization exists but will not be shown for the SoftwareNameplate submodel. +> We see the generic overview of submodel data. +> +>
](https://industrialdigitaltwin.org/wp-content/uploads/2023/07/2023-07-27_IDTA_Tutorial_V3.0-Specification-AAS-Part-2_API.pdf)\
+(
+Source: [IDTA](https://industrialdigitaltwin.org/wp-content/uploads/2023/07/2023-07-27_IDTA_Tutorial_V3.0-Specification-AAS-Part-2_API.pdf))
+
+A tutorial about the Discovery Service along with the registries can be
+found [on the IDTA website](https://industrialdigitaltwin.org/wp-content/uploads/2023/07/2023-07-27_IDTA_Tutorial_V3.0-Specification-AAS-Part-2_API.pdf).
+
+### How to connect Mnestix Browser to the different components
+
+#### Running Mnestix with its API
+
+There also exists the [Mnestix API](https://hub.docker.com/r/mnestix/mnestix-api), that provides different business
+comfort features.
+Here it is possible to set an API Key, for example, to secure your backend services like the repository or the discovery
+service.
+When running the [Mnestix API](https://hub.docker.com/r/mnestix/mnestix-api) you can change the paths to the different
+services like described in the [Mnestix API Documentation](https://hub.docker.com/r/mnestix/mnestix-api).
+For example (change `{{MNESTIX_BACKEND_API_URL}}` to the URL of the
+running [Mnestix API](https://hub.docker.com/r/mnestix/mnestix-api))
+
+```yaml
+DISCOVERY_API_URL: '{{MNESTIX_BACKEND_API_URL}}/discovery'
+AAS_REPO_API_URL: '{{MNESTIX_BACKEND_API_URL}}/repo'
+SUBMODEL_REPO_API_URL: '{{MNESTIX_BACKEND_API_URL}}/repo'
+MNESTIX_BACKEND_API_URL: '{{MNESTIX_BACKEND_API_URL}}'
+```
+
+#### Running Mnestix without its API
+
+This is the easiest configuration, for when you only want to visualize and browse through AAS.
+If you choose to run the Mnestix Browser without the Mnestix API, the Feature Flags `AUTHENTICATION_FEATURE_FLAG`
+and `AAS_LIST_FEATURE_FLAG` will be overwritten to `false` as these Features use the functionality of the API.
+The other environment variables should be configured [as described](#frontend-configuration). If you want to run Mnestix Browser with an Basyx environment you can simply use the compose.frontend file which is described [here](Docker-compose-files).
+
+#### How to configure the BaSyx AAS Repository
+
+We recommend the usage of Mnestix together with
+the [BaSyx AAS Repository](https://github.com/eclipse-basyx/basyx-java-server-sdk).
+This component stores all the different AAS (type 2), it is recommended to configure it to use a database for
+persistence.
+We recommend to set the following environment variables (replace `{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}` with the
+corresponding values):
+
+```yaml
+# Allow to upload bigger AASX files
+SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE: 100000KB
+SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE: 100000KB
+# Allow mnestix frontend and backend to call basyx
+BASYX_CORS_ALLOWED-ORIGINS: '{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}'
+BASYX_CORS_ALLOWED-METHODS: GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD
+```
+
+If you are using the Mnestix API see [here](#running-mnestix-with-its-api) on how to set the Frontend Flags.
+If you are using only the Mnestix Browser just set the environment variables `AAS_REPO_API_URL` and
+`SUBMODEL_REPO_API_URL` accordingly.
+
+#### How to configure the BaSyx Discovery Service
+
+We recommend the usage of Mnestix together with
+the [BaSyx AAS Discovery Service](https://github.com/eclipse-basyx/basyx-java-server-sdk/tree/main/basyx.aasdiscoveryservice).
+This component links Asset IDs to AAS IDs. It is recommended to configure it to use a database for persistence.
+We recommend to set the following environment variables (replace `{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}` with the
+corresponding values):
+
+```yaml
+# Allow mnestix frontend and backend to call discovery service
+BASYX_CORS_ALLOWED-ORIGINS: '{{MNESTIX VIEWER URL}}, {{MNESTIX API URL}}'
+BASYX_CORS_ALLOWED-METHODS: GET,POST,PATCH,DELETE,PUT,OPTIONS,HEAD
+```
+
+If you are using the Mnestix API see [here](#running-mnestix-with-its-api) on how to set the Frontend Flags.
+If you are using only the Mnestix Browser just set the environment variable `DISCOVERY_API_URL` accordingly.
+
+#### Technical Information - Discovery Service
+
+The functions that are described in
+the [Specification AAS - Part 2: API](https://industrialdigitaltwin.org/wp-content/uploads/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf)
+were implemented in the [`discoveryServiceApi.ts`](src/lib/api/discovery-service-api/discoveryServiceApi.ts).
+They make the respective `GET`, `POST` and `DELETE` requests to the specified `DISCOVERY_API_URL`.
+Two additional functions were added that simplify the usage of the Discovery Service by just requiring the globalAssetId
+and no additional AssetLinks.
+
+These functions are `LinkAasIdAndAssetId(aasId: string, assetId: string)` and `GetAasIdsByAssetId(assetId: string)`.
+The return of all functions is the response from the Discovery Service parsed as an object.
+So they can be used like in the example below:
+
+```typescript
+await LinkAasIdAndAssetId(aasId, assetId);
+const foundAasIds = (await discoveryServiceClient.GetAasIdsByAssetId(assetId)).result;
+```
+
+#### How to configure the BaSyx AAS Registry Service
+
+The AAS Registry Service is designed to provide descriptors for Asset Administration Shells (AAS),
+including endpoints to various repositories that may be stored elsewhere.
+This architecture ensures support for multiple repositories, provided they are registered in the designated AAS
+registry.
+
+When an AAS for the specified AAS-Id is found, it is displayed in the detail view. If the AAS is not found,
+the service will search in the local repository for the requested information.
+
+If the discovery service is configured, it will initially identify the relevant AAS-ID for the searched Asset ID before
+querying the Registry Service.
+Configuration of the Registry Service is optional. If the AAS Registry Service is not configured, the search will
+default to the local repository.
+
+To configure the AAS registry, please provide the URL in the Frontend Configuration variables.
+
+```yaml
+REGISTRY_API_URL: '{{REGISTRY-SERVICE-URL}}'
+```
+
+By setting the REGISTRY_API_URL, you enable the AAS Registry Service, ensuring efficient retrieval of AAS descriptors.
+
+#### How to configure the BaSyx Submodel Registry Service
+
+The Submodel Registry feature provides an optional configuration that allows you to manage and resolve submodels
+efficiently.
+When the Submodel Registry is configured, any reference to a submodel will first check if the submodel is available in
+the specified registry endpoint.
+If the submodel is found in the registry, it will be fetched from there. If the submodel is not found in the registry,
+the system will then check the local repository for the submodel.
+
+Configuring the Submodel Registry is optional. If not configured, all submodel references will default to being resolved
+from the local repository only.
+
+To configure the Submodel registry, please provide the URL in the Frontend Configuration variables.
+
+```yaml
+SUBMODEL_REGISTRY_API_URL: '{{SUBMODEL_REGISTRY_API_URL}}'
+```
+
+By setting the SUBMODEL_REGISTRY_API_URL, you enable the Submodel Registry Service, ensuring efficient retrieval of
+Submodel descriptors.
+
+#### Technical Information - Registry Service
+
+The functions that are described in
+the [Specification AAS - Part 2: API](https://industrialdigitaltwin.org/wp-content/uploads/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf)
+were implemented in the [`registryServiceApi.ts`](src/lib/api/registry-service-api/registryServiceApi.ts).
+They make the respective `GET`, `POST` and `DELETE` requests to the specified `REGISTRY_API_URL`.
+
+### Different Mnestix Configurations
+
+There are multiple scenarios possible on how to deploy the Mnestix Browser with different configurations.
+In the following, it is described, what scenarios were thought of and how to configure them
+
+#### I want to only view AAS
+
+If you just want to view AAS and integrate it into your existing environment, you can run only the `mnestix-viewer`
+without its API.
+See [Running Mnestix without its API](#Running-Mnestix-without-its-API).
+
+#### I want to use more advanced features
+
+There are also some more advanced features one might want to use.
+For this you need to enable the Mnestix API, see [here](#running-mnestix-with-its-api).
+It enables you to secure all `POST/PATCH/DELETE`-Request with an API-Key.
+The API-Key needs to be sent within the Header `ApiKey` to make those requests.
+Normal `GET/FETCH`-Requests are not affected by this.
+
+When using it is also possible to restrict some functions that you possibly don't want to be accessible.
+For example, it is possible to restrict the access to the `/shells` endpoint of the AAS repository by setting the
+backend environment variable `Features__AllowRetrievingAllShellsAndSubmodels: false`.
+Remember that this also means that the functionality to list all AAS won't work anymore in the Mnestix Browser, so
+disable this functionality with the environment variable `AAS_LIST_FEATURE_FLAG: false`.
+
+#### AAS List V2 Feature Details
+
+The `AAS_LIST_V2_FEATURE_FLAG` is a feature flag introduced as part of a preview release.
+It enables access to an updated list implementation that operates independently of the Mnestix API.
+
+This flag is currently disabled by default (false) and is available only in preview.
+It is not yet recommended for production environments.
+
+To enable the feature for testing or preview purposes, set the flag to true in your configuration.
+
+#### AzureAD Service
+
+One can also add an AzureAD Service to give people deeper access, this enables the "Login" Button in the Mnestix
+Browser.
+After logging in, users have access to even more functionality.
+To see how to connect to an Azure Tenant and enable the login functionality see
+the [official Mnestix API documentation](https://hub.docker.com/r/mnestix/mnestix-api).
+
+#### I want to create multiple AAS
+
+This option builds upon the advanced features described in
+the [previous section](#i-want-to-use-more-advanced-features).
+After logging in it is possible to configure the ID Generation Functionality of the backend.
+Here it is possible to automatically generate AAS using only a short ID of the Asset.
+How the AAS Creator in conjunction with the ID Generations Functionality works can be seen in
+the [official Mnestix API documentation](https://hub.docker.com/r/mnestix/mnestix-api).
+
+One can also use the Template Builder with the Data Ingest Endpoint to send arbitrary JSON files to the API and
+automatically add them to a specified AAS.
+This enables easy integration into existing ETL processes.
+How exactly this works can be seen in
+the [official Mnestix API documentation](https://hub.docker.com/r/mnestix/mnestix-api).
+
+Below you'll find a small overview on how the components interact with each other:
+
\ No newline at end of file
diff --git a/wiki/Secret-Environment-Variables.md b/wiki/Secret-Environment-Variables.md
new file mode 100644
index 00000000..4a6701aa
--- /dev/null
+++ b/wiki/Secret-Environment-Variables.md
@@ -0,0 +1,13 @@
+You can (and should) create your personal `.env` file in the root directory.
+Simply rename `.env.example` to `.env` and enter your secrets.
+The secrets may be arbitrary strings.
+
+This `.env` file will be used automatically by docker compose and Next.js.
+
+```yaml
+AD_SECRET_VALUE: '<+
\ No newline at end of file From 25b316b14ba2c8fabdf01d4559fb698195ff2af7 Mon Sep 17 00:00:00 2001 From: NilsXitaso
-
\ No newline at end of file +
+
\ No newline at end of file From 6eed7ec209d905f19afe9c200ea9b865d3e63526 Mon Sep 17 00:00:00 2001 From: Melanie Gail