Creating a Transformation Configuration

The following section provides some fundamentals from AutomationML required for creating the configurations.

Example AutomationML structure

Sample Code

<?xml version="1.0" encoding="UTF-8"?> 
<CAEXFile xmlns="http://www.dke.de/CAEX" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="3.0" FileName="aml_minimal_sample.xml" xsi:schemaLocation="http://www.dke.de/CAEX CAEX_ClassModel_V.3.0.xsd"> 
    <SuperiorStandardVersion>AutomationML 2.10</SuperiorStandardVersion> 
    <SourceDocumentInformation OriginName="" OriginID="" OriginVersion="" LastWritingDateTime="2020-06-12T12:46:56.7231137+02:00" /> 
    <SystemUnitClassLib Name="TestSystemUnitClassLib"> 
        <SystemUnitClass Name="MyAssetName" ID="TestSystemUnitClassID"> 
            <Attribute Name="IdentificationData"> 
                <Attribute Name="Manufacturer"> 
                    <Value>TestManufacturer</Value> 
                </Attribute> 
                <Attribute Name="ManufacturerURI"> 
                    <Value>http://www.example.com/manufacturerURI</Value> 
                </Attribute> 
                <Attribute Name="Model"> 
                    <Value>TestModel</Value> 
                </Attribute> 
            </Attribute> 
            <SupportedRoleClass RefRoleClassPath="AutomationMLComponentStandardRCL/AutomationComponent" /> 
        </SystemUnitClass>

AutomationML exploits CAEX for modeling the system topology and the system elements. It provides four main modeling elements:

Role classes: collected within role class libraries. A role class describes an abstract functionality without defining the underlying technical implementation, thus, it has to be seen as an indicator for the semantics of an object.
Interface classes: An interface class describes an abstract relation an element can have to other elements or to information not covered within the CAEX-based model. Each AutomationML user can define new interface classes following its use cases and needs for data exchange.

AutomationML only defines some rules for interface class definition. Each interface class can have attributes. These attributes have to be used and filled with values in each occurrence of an instance of the interface class.
System unit classes: System unit classes can be considered as reusable system components or as templates for system modeling depending on the point of view.

Usually, they reflect either a vendor-dependent library of components or devices, or a set of templates used within an engineering tool to structure discipline-dependent model information.
The Instance-Hierarchy with its integrated hierarchy of InternalElements. It represents the actual engineering data to be modeled by CAEX following an object-oriented and hierarchical structure.

Main structure of a configuration file

Sample Code

{
    "version": "1.0.0",
    "aasVersion": "3.0RC01",
    "placeholders": [
        {
            "name": "assetName",
            "description": "Name of the asset"
        },
        {
            "name": "submodelName",
            "description": "Name of the submodel"
        }
    ],
    "configMappings": [
        {
            "from_xpath": "//caex:SystemUnitClass",
            "assetInformation": {},
            "assetShell": {},
            "submodels": []
        }
    ]
}

Placeholders: The list of placeholder variables that are to be replaced in the configuration.
from_xPath: Navigate xPath to this XML node in AML file.
assetInformation: The information relevant for populating the "assetInformation" element of the AAS (for example, assetKind and globalAssetId).
assetShell: Information about the "AssetAdministrationShell" element of an AAS json, such as the Identification and IdShort elements.
submodels: An array, each element of which contains the information for creating individual submodels that describe a domain or use-case of an asset.

assetInformation object

Sample Code

{
"kindType_xpath": "TYPE",
"globalAssetIdReference": {
"valueId": "${{UUID}}",
"keyType": "CUSTOM",
"keyElement": "ASSET"
}
}

The assetInformation element describes the meta information about the represented asset including its globalAssetId.

assetShell object: The model short description and the model internalId are defined by this object.

assetShell configuration: An assetShell in the configuration file corresponds to a Model in SAP Asset Intelligence Network. To create an assetShell only the identification of the Asset and the idShort are required. The respective configuration part looks like this:

Sample Code

{
"idGeneration": {
"parameters": [
{
"from_string": "${{ModelInternalId}}"
}
]
},
"idShort_xpath": "'${{ModelShortDescription}}'"
}

The idGeneration defines the ID of the assetShell that is mapped to the Model internalId.

The idea of having submodels is that one can reuse them as templates in various AML files to extract information in a standardized way.

A submodel is represented by a Model Template. The configuration has the following structure:

Sample Code

{
    "from_xpath": ".",
    "semanticId_ref": {
        "valueId": "http://www.sap.com/ain/identificationData",
        "keyType": "IRI",
        "keyElement": "SUBMODEL"
    },
    "idGeneration": {
        "parameters": [
            {
                "from_string": "IdentificationSubmodelId"
            }
        ]
    },
    "idShort_xpath": "'IdentificationData'",
    "submodelElements": []
}

from_xpath: the path in the XML node structure where the navigation from XPath should start (selecting the current node in the xml).
semanticId_ref: this is the mapping key to the template object in SAP Asset Intelligence Network.
idGeneration: define the internal ID of the template object.

Note

The from_string key means that the internal ID of the template object will be the value of this string and not found in the AML file.
submodelElements: An array containing the child objects of the template object.

Note

In SAP Asset Intelligence Network, it is not possible to have attributes, directly as children to templates (they should be placed into a NestedStructure or AttributeGroup). Therefore, Properties as submodelElements must always be placed in a SubmodelElementCollection.

A submodelElementCollection is mapped to a NestedStructure or AttributeGroup.

Sample Code

{
    "submodelElements": [
        {
            "from_xpath": ".",
            "@type": "SubmodelElementCollection",
            "semanticId": "http://www.sap.com/ain/identificationData/collection",
            "submodelElements": [
                {
                    "semanticId": "0112/2///61987#ABA565",
                    "from_attributeName": "Manufacturer",
                    "@type": "Property",
                    "valueType": "string"
                }
            ]
        }
    ]
}

A submodelElementCollection contains a list of SubmodelElements. A SubmodelElement can be either another SubmodelElementCollection (will be mapped to another NestedStructure or AttributeGroup) or a dataelement like a Property (mapped to an attribute in SAP Asset Intelligence Network).

The mapping of Properties to individual XML elements of the AutomationML file, takes place through the Properties elements. The configuration of a property element below instructs that the value of the AML Attribute Element with "Name = Manufacturer".

Identification Submodels:

The Identification Submodel is mandatory for EVERY configuration. This is required to map business partner of AIN to a manufacturer field. Following conditions must be met:

The transformation config json must contain a submodel with following elements:
- Submodel
  - Semantic Id: http://www.sap.com/ain/identificationData
  - Internal Id: IdentificationData
- A submodelElementCollection
  - Semantic Id: http://www.sap.com/ain/identificationData/collection
  - Internal Id: IdentificationData
- A Property
  - Semantic Id: 0112/2///61987#ABA565
  - Internal Id: Manufacturer

Placeholders

Placeholders are variables that are used in the configuration file that are to be filled during runtime. They are used to pass information such the asset name from the UI, in order to make the configuration reusable for different contexts and AML files.

The placeholders are declared in the root element of the configuration json.

Sample Code

{
    "placeholders": [
{
"name": "UUID",
"description": "UUID of the Model"
},
{
"name": "ModelInternalId",
"description": "InternalId of the Model"
},
{
"name": "ModelShortDescription",
"description": "Short description of the Model"
}
]
}

In this example, UUID, ModelInternalId, and ModelShortDescription are declared as a placeholder that should be given as a parameter to the aml transformation. In the configuration file, they are reference like this: ${{Name of the Placeholder}}, for example, ${{UUID}}.