Target Model Identification Form OPC UA
This version of the TMI Form supports the standard OPC UA specification.
Apis Management Studio (AMS) is used when exporting/importing TMI forms. The TMI form itself is an Excel spreadsheet (xlsx), which can be manipulated by humans.
When building models in a TMI form, the recommended workflow is to first build a small part of the model in the model builder in AMS using the OPC UA perspective. This small part should span as much of the model as possible, i.e. contain the types used and one or more paths down to the leafs of the model. When exporting this model to a TMI form, the layout of the TMI will be correct and make a good starting point for manually adding entities to the model. After entities are added/changed in the TMI form, the form can be imported to the UA server to update the semantic model.
Read this page for an overview of the TMI Form, then further documentation can be found here:
To export to TMI form, see Target Model Identification Export.
To import from TMI form, see Target Model Identification Import.
To import in bulk, see Import in Bulk.
TMI form explained
In the following a simple model of a room with a pump is used to explain the workings of the TMI Form. The pump has variables; pressure, rpm.
Exporting the model to a TMI Form will result in an Excel file with a number of sheets. The sheets contains all the information needed to create or update this model. Objects of the same type are defined in the same sheet. There may be several sheets for the same type, depending on the hierarchy of the model.
Objects may have variables (variables of type BaseDataVariableType or descendants) and/or Properties (Attributes, of type PropertyType) associated with them. The variables of the objects have their own sheet with the same name as the associated object sheet, postfixed with '_VT'. The Properties of objects also have their own sheet with the same name as the associated object sheet, postfixed with '_PT'.
The content of the sheets will now be explained:
The Master sheet
The Master sheet contains information about the UA Types of the objects in the model; how types are used in the model hierarchy, and in which sheet to find them.
| Column Name | Explanation |
|---|---|
| Type | The UA type, with namespace index, of the objects in this sheet. The number before the type name is the namespace index. The index is defined in the Namespaces sheet. The hierarchy of the model is suggested by spaces between ':' and the type name. If you enter types manually, you need not add spaces, the spaces are for visualization only. |
| Sheet | Name of the sheet where the objects are defined. This name must be unique and correspond exactly with the name of the sheet. The name is limited to 29 characters (by Excel). The names are auto generated on export. The prefix of the sheet name reflects the hierarchy of the model ('1-1>' above). In the example above, '1-1>', says that instances in this sheet has parents in sheet 1 (the first 1). The second 1 indicates the instances number (of this type). The sign '>' indicates if the modelling rule is a placeholder (Optional-/MandatoryPlaceholder). If the last sign is '.', it is not a placeholder. |
| Include in import | Setting this false will make the importer ignore instances in this sheet. This can be useful if the model is large and you have made changes to a small part of the model. |
The Namespaces sheet
The Namespaces sheet contains the namespaces used in the model. It also contains the namespace index for each namespace. The index is used elsewhere in the TMI as part of the UA types. Namespace indexes may vary from server to server and after restart of servers. This table is used as a map when importing to a server, and it is never necessary to change the index in the file.
| Column Name | Explanation |
|---|---|
| Namespace | The namespace URI. |
| Index | The namespace index associated with a namespace. The index may vary between servers and server restarts. Never change the Index in a TMI |
| EU Namespace | The namespace URI of engineering units. |
| Index | The namespace index associated with a EU namespace. The index may vary between servers and server restarts. Never change the Index in a TMI |
The Object sheet
There may be many object sheets, with different names. This example shows the sheet called 1>BaseObjectType from our pump room example. Instances of type BaseObjectType will be in this sheet, as defined in the Master sheet. To add more objects of BaseObjectType, simply add rows in this sheet and type in the data for the objects.
| Column Name | Explanation |
|---|---|
| RelativePath | The relative path from the top node (the node that was selected for export). The RelativePath is a series of DisplayNames separated by '/'. See later examples of this. You may reference instances outside of your model. The RelativePath will then start from the Objects node, Object/SomeOject... An instance may have multiple parents, in this case, the relative paths are all entered, separated by ';'. In this case The Reference column must also contain all references, separated by ';', in the same order as in RelativePath. |
| Reference | The reference to this instance from its parent. Note that no namespace index is needed, it is assumed that references are not extended and therefore are unique by name. |
| BrowseName | The BrowseName of the object. |
| DisplayName | The DisplayName of the object. If left blank, the object will not be created unless the ModellingRule is Mandatory. |
| NodeId | The NodeId of the object. If left blank, it will be generated on import. |
| Description | The Description attribute of the object. |
| ModellingRule | The ModellingRule of the object. This column is for information only, and will not be set on import. The ModellingRule is defined in the type this object is a part of. |
Lets look at another object sheet, 1-1>BaseObjectType:
We see from the RelativePath column that this pump is a child of PumpHouse.
The variable sheet
The variable sheet defines variables for objects in the Object sheet. Each Object sheet has an associated variable sheet. The variable sheet has the same name as the object sheet, postfixed with '_VT'.
All types in this sheet is, or inherits, BaseVariableType. In addition to standard properties (of type PropertyType) of BaseVariableType, properties from the UA DataAccess definition are added in this sheet, for convenience.
The UA DataAccess properties are:
- InstrumentRange
- EURange
- EngineeringUnits
- Definition
- ValuePrecision
- TrueState
- FalseState
Any properties outside this scope are located in the _PT sheet (PropertyType sheet).
The variable sheet for instances in 1-1>BaseObjectType, is:
| Column Name | Explanation |
|---|---|
| RelativePath | The relative path from the top node (the node that was selected for export). The RelativePath is a series of DisplayNames separated by '/'. |
| Reference | The reference to this instance from its parent. Note that no namespace index is needed, it is assumed that references are not extended and therefore are unique by name. |
| Type | UA type of this variable. A type that inherits from BaseVariableType. |
| BrowseName | The BrowseName of the instance. |
| DisplayName | The DisplayName of the instance. If left blank, the instance will not be created unless the ModellingRule is Mandatory. |
| NodeId | The NodeId of the instance. If left blank, it will be generated on import. |
| Description | The Description attribute of the instance. |
| ModellingRule | The ModellingRule of the instance. |
| InitialValue | The initial value of the variable. The value the variable will have after an Apis restart. This can be useful for variables that are not mapped. |
| DataType | The data type of the variable value. |
| EngineeringUnits | Unit of the variable. See the Unit sheet for all available units. |
| EngineeringUnitsId | The NodeId of the EngineeringUnits property. If left blank, it will be generated on import. |
| EURange | Normal operating range for this value. |
| EURangeId | The NodeId of the EURange property. If left blank, it will be generated on import. |
| InstrumentRange | The value range that can be returned by the instrument. |
InstrumentRangeId | The NodeId of the InstrumentRange property. If left blank, it will be generated on import. |
| ValuePrecision | The maximum precision that the server can maintain for the value. |
ValuePrecisionId | The NodeId of the ValuePrecision property. If left blank, it will be generated on import. |
| Definition | A vendor-specific, human readable string that specifies how the value is calculated. |
| DefinitionId | The NodeId of the Definition property. If left blank, it will be generated on import. |
| StoreToIMS | Store the value to a historian. |
| StoreToIMSId | The NodeId of the StoreToIMS property. If left blank, it will be generated on import. |
| FalseState | String to be associated with this value when it is FALSE |
| FalseStateId | The NodeId of the FalseState property. If left blank, it will be generated on import. |
| TrueState | String to be associated with this value when it is TRUE |
| TrueStateId | The NodeId of the TrueState property. If left blank, it will be generated on import. |
| Expression | An expression used to calculate the value |
| ExternalItem1 | An external item that the value depends on. There may be more than one ExternalItem. Make a new column for each and name them ExternalItem2 ... ExternalItemN |
The Property sheet
The Property sheet defines properties of the UA type PropertyType. Each Instance sheet has an associated Property sheet. The Property sheet has the same name as the object sheet, postfixed with '_PT'. Some properties are, for convenience, in the Object and Variable sheets, the rest of the properties are in this sheet. Properties of objects and properties their variables are listed in this sheet. We can see from RelativePath in the sheet below that the property 'SerialNo' is a property of object 'Pump1'.
| Column Name | Explanation |
|---|---|
| RelativePath | The relative path from the top node (the node that was selected for export). The RelativePath is a series of DisplayNames separated by '/'. |
| Reference | The reference to this property from its parent. |
| PropertyType | The UA type of the property. |
| BrowseName | The BrowseName of the property. |
| DisplayName | The DisplayName of the property. If left blank, the property will not be created unless the ModellingRule is Mandatory. |
| NodeId | The NodeId of the property. If left blank, it will be generated on import. |
| Description | The Description attribute of the property. |
| ModellingRule | The ModellingRule of the property. |
| Value | The value attribute of the property |
| DataType | The data type of the value |
The Unit sheet
The Unit sheet contains all available units on the UA server when the model was exported. Values defined for the EngineeringUnits property are units from this list. In the TMI form, a drop-down that contains all units is available for all EngineeringUnits. You can type only the DisplayName of the unit if you want, the first unit that matches the DisplayName will then be selected (the same DisplayName may appear in several namespaces). The format of the unit code is [eu namespace index]:[displayname][[id]].
| Column Name | Explanation |
|---|---|
| DisplayName | The DisplayName of the unit |
| Description | The Description of the unit |
| Id | A unique unit id |
| EU Namespace | The namespace of the unit |
| Code | A code used to uniquely define a unit in the spreadsheet |