How to Create Custom Submodel Visualizations

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.

Important

For a starting point we provide an example submodel visualization at SoftwareNameplate. 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 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.

As for any other contribution to Mnestix, you will have to start by forking the GitHub repository. You can find the option to fork a repository on the main page of the repository.

This will create a new repository with a copy of the Mnestix source code. After creating the fork, you can clone the repository locally and start developing.

2. Create your React component

You can find all currently existing submodel visualizations at the following path: src/app/[locale]/viewer/_components/submodel. Before creating your React component, we suggest to create a directory for your submodel (element) visualization inside src/user-plugins to put all your components in.

Important

To clone the software nameplate you can 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 find the example AAS for the SoftwareNameplate with the ID https://vws.xitaso.com/aas/mnestix.

Creating a visualization for a submodel

After you created the sub-directory for your own visualizations, 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:

import { SubmodelVisualizationProps} from 'app/[locale]/viewer/_components/submodel/SubmodelVisualizationProps';

export default function CustomSubmodel({submodel}: SubmodelVisualizationProps){
    return (
            <h1>This is the custom visualization for submodel {submodel.idShort}</h1>
    );
}

Important

For now the custom visualization will not be shown for the SoftwareNameplate submodel. We see the generic overview of submodel data.

Map the visualization

In order for Mnestix to automatically use your visualization, you have to provide the mapping between your visualization and the semantic id which your custom visualization should be used for. This is done in the file src/app/[locale]/viewer/_components/submodel/SubmodelsCustomVisualizationMap.ts which looks similar to this:

export const submodelsCustomVisualizationMap = {
    [SubmodelSemanticId.CoffeeConsumptionContainer]: CoffeeConsumptionDetail,
    [SubmodelSemanticId.CarbonFootprint]: CarbonFootprintDetail,
    [SubmodelSemanticId.CarbonFootprintIRDI]: CarbonFootprintDetail,
    [SubmodelSemanticId.ReferenceCounterContainer]: ReferenceCounterDetail,
    [SubmodelSemanticId.TimeSeries]: TimeSeriesDetail,
    [SubmodelSemanticId.HierarchicalStructuresV10]: HierarchicalStructuresDetail,
    [SubmodelSemanticId.HierarchicalStructuresV11]: HierarchicalStructuresDetail,
    [SubmodelSemanticId.BillOfApplications]: BillOfApplicationsDetail,
    [/*Your semantic id as a string*/]: /*React component name*/, 
};

Just add an entry containing the semantic id as a key and your React component as the value. Important: Don’t forget to import your React component at the top of the file! You might also want to add your semantic id to the SubmodelSemanticId-enum used in the examples above. This especially makes sense for standardized submodels.

Important

For the SoftwareNameplate the added mapping line will be ['https://admin-shell.io/idta/SoftwareNameplate/1/0']: SoftwareNameplateDetail,. We see the visualization now, but are still lacking the internationalization.

3. Reading data from your submodel

You probably want to display some information from the submodel. We provide you with a convenience method to search for a specific value in the submodel. Import and use it as follows:

import { findValueByIdShort } from 'lib/util/SubmodelResolverUtil';
const value = findValueByIdShort(submodel.submodelElements, 'MyIDshort', 'en');

It will automatically return the correct language value for a MultiLanguageProperty.

Important

We use the data finder to collect all the information. We first load the current website language with useLocale.

import { useLocale } from 'next-intl';
import { findValueByIdShort } from 'lib/util/SubmodelResolverUtil';

export function SoftwareNameplateVisualizations({ submodel }: SubmodelVisualizationProps) {
   const locale = useLocale();
   const link = findValueByIdShort(submodel.submodelElements, 'URIOfTheProduct', locale) ?? '';
   const manufacturer = findValueByIdShort(submodel.submodelElements, 'ManufacturerName', locale) ?? '';
   ...
}

4. Internationalization

You can put your translations in src/user-plugins/locale under your own submodel object. Be aware that this file is shared by all user-plugins so merge the files individually. For a full documentation of what is possible with next-intl visit their website.

Important

We have provided the locale files in the repository, but you still need to merge them with the user-plugin locale files. The merged file for locale/en.json whould look something like this:

{
  "user-plugins": {
    "submodels": {
      "hello-world-component": {
        "title": "Hello World!"
      },
      "SoftwareNameplate": {
        "welcome": "Welcome to Mnestix by",
        "slogan": "Asset Administration Shell made easy!",
        "versionInfo": "This is Mnestix version {version}. It was released on {releaseDate}."
      }
    }
  }
}

Now the submodel visualization will show the translated values from the internationalization file.

5. (Optional) Create a pull request

Especially when you are creating a visualization for a standardized submodel, we encourage you to contribute it to the Open Source Mnestix repository, so that others can profit from it as well! This can be done by creating a pull request on the GitHub page, like seen in the following picture:

After clicking on “New pull request”, you can select “Compare across forks” and select your own repository, like seen in the picture below:

Make sure to select the dev branch as the base branch!

After you have created the pull request, it will get reviewed and merged, as soon as everything is fine and the request got approved.

In case you don’t want to share your visualization with the public, you don’t have to create the pull request. Just be aware, that your project will from now on live in its own repository and not automatically get any updates from the main repository. In order to get updates, you will have to manually merge the main repository in to your forked project with every new update. Furthermore, you have to build and publish the docker image by yourself if you wish to use your custom visualization in a productive environment.