Device Mapping¶

In order to correlate the device simulators and their measurements to assets and their aspects you need to define a mapping. This can be done manually by "Asset Mapping" provided in the Device Management Application. Therefore, go to Device Management > Asset Mapping.

The main view is separated into two panels: Navigation (containing Devices and Assets) and Mappings area. On the navigation panel, the left side shows all available device groups and devices. The right-hand side shows all available assets of the related environment. A table below shows the current mappings.

On the top there are filters which can be applied to the device and asset view. Depending on the default view setting (Configuration), the devices are shown in a list or in a group view showing the devices within their groups. If the group view is enabled, the search applies to group names only. When devices should be searched by name, the "All devices" view can be used.

Differences among available kinds of mappings¶

Measurement mappings are the usually used mappings to map measurements/ data-points of a device to an (dynamic) aspect of an asset.

In case of non-number values event-data mappings can be used, if it is needed to map those non-number values like Strings to an (dynamic) aspect of an asset. In this case those values can be send by the device as an event. An event-data mapping can then be configured to take the content from the event-data mapping and transmit it to the mapped aspect.

For device information which should be transmitted to Insights Hub metadata mappings can be used. Any arbitrary metadata provided in the device object can be mapped to a static aspect.

For device related events and alarms which should be transmitted to Insights Hub, event mappings and alarm mappings can be used respectively. Both events and alarms can be mapped to events.

Create a mapping¶

To create a mapping proceed as follows:

1. Select a device on the left-hand side of Navigation Panel. (You can see available data-links in the dropdown menu in the Mappings-Area)
2. Select an asset on the right-hand side of Navigation Panel.
3. Click "+ Add Mapping". (You can only add a new mapping when you select a device and an asset)
4. Specify mapping details in the dialog.

In case of many devices and assets, the search text fields for each section can help finding devices or assets on navigation panel.

• The search auto applies once you hit the "Return" (Enter) key.
• Also: if you delete the existing search string and click "Return", all devices and assets are shown again. (If the filter type is set to "SHOW ALL", this will show the "group view")
• Enter at least 3 characters to activate the search immediately without hitting the "Return" key.
• "Clear all" is implemented inside the search box which clears the entered text and shows the "Group view".

Click on "Clear selection" to clear the selection on the navigation panel.

After clicking "+ Add Mapping" a dialog appears to select the mapping information of the selected device and asset. The "+ Add Mapping" button is disabled in case the selected device and asset are mapped using a template.

There are several options to add a mapping:

1. Choose from existing mapping template:
   • Select a template from the drop-down menu.
   • Click "+ Add" to apply this template to the selected device and asset.
2. Add measurement (data point) mapping:
   • Select the required "Source", "Target" and "Converter" information:
     1. "Measurement": Source measurement of IoT Extension
     2. "Series": Source series within selected measurement of IoT Extension
     3. "Aspect": Target aspect of Insights Hub
     4. "Variable": Target variable within selected aspect of Insights Hub
     5. "Converter": Possible conversion of units of measurement from Source to Target (e.g. Celsius to Fahrenheit)
3. Add event-data mapping:
   • This process is very similar to measurement mapping.
     1. "Event Type": Select from all event types the device is sending
     2. "Event Property": (optional): Select specific property of the event
     3. "Aspect Name": Select aspect of chosen asset
     4. "Variable": Select variable of selected aspect
     5. "Converter": Possible conversion of units of measurement from Source to Target (e.g. Celsius to Fahrenheit)
4. Add metadata mapping:
   • This process is very similar to measurement mapping and event-data mapping.
     1. "Property Name": Select from all device properties
     2. "Aspect Name": Select aspect of chosen asset
     3. "Variable": Select variable of selected aspect
     4. "Converter": Possible conversion of units of measurement from Source to Target (e.g. Celsius to Fahrenheit)
5. Add event mapping:
   • Select the required "Source" and "Target" information:
     1. "Event Type": Select from all event types the device is sending.
     2. "Event Type": Type in the event type which should be used for event creation. After typing in first three letters, press enter. The dropdown displays the available event type starting with entered letters.
     3. “Severity”: Enter the severity of the event. By default, the severity is 40.
   • Add Custom Field Mapping (optional): Click on "Add custom field mapping" to map specific properties of the events between IoT Extension and Industrial IoT.
     1. “Source Property”: Select specific property of the event.
     2. “Target Property”: Select specific property of the event to which source property should be mapped. It is possible to add multiple custom mappings in an event mapping.
6. Add alarm mapping: The creation of alarm mapping is similar to the creation of event mapping. However, in case of alarm mapping, an alarm type is mapped to an event type. Based on the created alarm mapping, a device alarm is mapped to a event. A "1:1" mapping is maintained between an alarm in IoT Extension and an event in Insights Hub based on their IDs. For a new instance of an alarm of the mapped alarm type raised in IoT Extension, a new event is created in Insights Hub. Any further update to that alarm would trigger an update of the same event until the alarm is set to "CLEARED". Once an alarm is cleared, another device alarm of the same alarm type would be mapped to a new event in the Insights Hub.

• Select the required "Source" and "Target" information:
  1. “Alarm type”: Select from all alarm types.
  2. "Event Type": Type in the event type which should be used for event creation. After typing in first three letters, press enter. The dropdown displays the available event type starting with entered letters.
  3. “Severity”: Enter the different severities of the alarm. Based on severity of the alarm selected in source, one of the four severity in target is used during event creation. By default, the severity is 20 for critical and major alarms and 30 for minor and warning alarms.

• Add Custom Field Mapping (optional): Click on "Add custom field mapping" to map specific properties of the events between IoT Extension and Industrial IoT.
  1. “Source Property”: Select specific property of the alarm.
  2. “Target Property”: Select specific property of the event to which source property should be mapped.

It is possible to add multiple custom mappings in an alarm mapping.

Clicking on "+ Add" creates a mapping between source and target. You can add more mappings by repeating the above steps.

At this state the mapping is not committed yet. Mappings must be committed (published) by clicking on "Commit Changes" and applying those changes in the confirmation dialog box. This action activates all mappings immediately. As long as there are no mappings to commit, nothing will be shown in "Commit Changes" pop up.

Mappings of any devices or assets are shown on demand. (No mappings will be shown unless any device / asset is selected)

• Mappings can be sorted based on the Measurement, Series, Aspect Name, Variable and Status.
• Mappings can be deleted by clicking on the "trash" icon.
• If no mapping is found for the device or asset, the following notification appears:

Existing mappings can be saved as template:

Delete a mapping¶

Deleting single mappings can be done as soon as a device or an asset and one of its datalinks is selected.

The datalink between a device and the onboarded asset can be deleted by selecting it and clicking on the trash-icon afterwards. We can choose whether the created asset should be deleted or not. In any case the locked asset will be unlocked when deleting the datalink.