DeviceHub Bulk Upload Tags

Estimated reading time: 9 minutes

Typically, in a large environment, data needs to be collected from hundreds of device registers. In this case, adding tags one by one is a daunting task. OT Link Platform DeviceHub makes that task easier with a bulk load option, which creates tags from an uploaded comma-separated-values (CSV) file. This attribute values in the CSV file can be derived from DeviceHub Devices and from register definitions supplied by PLC vendors.

Use the following information to complete the bulk-loading task:

For additional tag-management tasks, see DeviceHub Manage Tags.

Overview of DeviceHub Tag Bulk Loading

Prerequisite

A DeviceHub device must be configured for the specific device and driver, for example, Allen-Bradley Micrologix. See DeviceHub Add, Monitor, or Delete Device.

The goal of this bulk-loading operation is to add a large set of tags/registers to OT Link Platform, as illustrated in the following DeviceHub Tags list. To add just a single tag, see DeviceHub Add a Tag.

Download the Sample CSV File Template

OT Link Platform provides a template of the required fields.

Go to DeviceHub > Tags.
Click the at the right of the window.
Select Upload CSV from the list.
Click Download Sample CSV.

A tag-template.csv file downloads.
Populate the CSV File

Populate the CSV File

A row/record for each tag must be populated with attribute values, as described below. Refer to the PLC’s register definitions for details.

Using the downloaded template, add a row for each tag to be added.
Keep the header row as defined in the template:

deviceId

deviceName

driverName

registerName

tagName

description

valueType

address

dbNumber

pollinginterval

omaObjectId

omaInstanceId

omaResourceId

omaValueType

Backward compatibility for previous CSV versions

If you are using a CSV file from a previous OT Link Platform version:

Check the downloaded CSV template to verify that all columns are present in your CSV file. Additional columns may have been added or columns may have been renamed.
The order of the attribute columns in the latest CSV template may be different from previous versions. The columns can be in any order.

Example of a Tag CSV File

deviceId	deviceName	driverName	registerName	tagName	description	valueType	address	dbNumber	pollinginterval	omaObjectId	omaInstanceId	omaResourceId	omaValueType
0b55610e-d501-4b68-832c-ca392aa20faa	Siemens-S7-D1	siemens_snap7	C5:0.PRE	D1000		bit	10	1	1	3303	0	5700	Boolean
	Siemens-S7-D1	siemens_snap7	C5:0.PRE	D1001		bit	10	2	2	3303	1	5700	Boolean

Definition of Tag Attributes

For OMA object and resource details, refer to the device vendor documentation, as well as this reference page: IPSO Object Reference Guide.

Tag Attribute Rules

Either deviceId or deviceName can be omitted, but not both. One of these fields is required to find the corresponding device.
- If a device identified by the deviceId is not found, the entire tag record is rejected.
- If a device identified by the deviceName is not found, this is not an error and the tag record is added.
Attribute values are required unless noted as optional.
- If an optional value is null, it is ignored. This allows for the loading of register definitions for multiple device types from a single file.
- If the value is null and the device driver defines it as mandatory, the tag will not be imported.
- If an optional value is present in the CSV file, but it is not supported by the device driver, it is treated as an error and the tag will not be imported.
Attribute columns in the CSV can be in any order.

Attribute Name	Data Type	Sample Value	Description	Notes
deviceId	string	"0b55610e-d501-4b68-832c-ca392aa20faa"	ID of the device (optional)	Click the pages icon next to the very long device ID in the DeviceHub device card to copy the device ID. If a device identified by the `deviceId` is not found, `deviceName` is used.
deviceName	string	"Siemens-S7-D01773"	Name of the device (used if deviceId is not provided)	Copy the user-defined name for the device from the DeviceHub device card. If a device identified by the `deviceName` is not found, this is not an error and the tag record is added.
driverName	string	"siemens_snap7"	Driver name is for validating optional attributes against registration.json. This type should directly correspond to the name of the driver package.	Click the pages icon next to the driver name in the Device card to copy the driver name. Using this mandatory driver name, along with the device name, enables a user to replicate the device with the same tags over multiple OT Link Platform systems.
registerName	string	"C5:0.PRE"	PLC register name or full PLC register address	This name is case sensitive.
tagName	string	"D1000"	Tag name that will be displayed in DeviceHub	Often this is a combination of the register and address
description	string		Any text (optional)	An optional user-supplied description for each tag
omaObjectId	integer	3303	OMA Object ID (optional)	The numeric ID for the OMA object. Example for a temperature sensor object: 3303 All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag.
omaInstanceId	integer	0	OMA Instance ID (optional)	All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag.
omaResourceId	integer	5602	OMA Resource ID (optional)	Example for the maximum measured value of a temperature sensor object: 5602 All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag.
omaValueType	string, one of: String Integer Float Boolean Opaque Time Objlink	"Boolean"	OMA value type (optional)	All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag.
`valueType`	string	"bit"	Type of the register value	Examples: bit, word
address	integer	10	Register address	Refer to the PLC vendor's guide for a list of valid addresses.
dbNumber	integer	1	Siemens dbNumber (optional)	This is a device-specific attribute. Refer to the PLC vendor's guide for a valid list.

CSV Formatting and Escaping Rules

Because CSV format is not standardized, several different methods could be used for escaping special characters. And, depending on locality, a different value separator may be used. For example, in European countries, a semi-colon is widely used as a separator. The OT Link Platform CSV specification adheres to the rules used by Microsoft Excel, as listed below.

Field separators can be comma ( , ), semicolon ( ; ), or tab ( \t ).
Fields can have white spaces around them. This space is removed during processing.
Fields can be escaped with double quotes ( “ ) or single quotes ( ‘ ). Leading or trailing white spaces inside the quotes are preserved.
Any separator characters within a quoted field is treated as part of the field value.
Any quotation character in a field value must be escaped with a backslash ( \ ) character.
Fields are parsed based on their data type: string values are read “as is” and numeric values are parsed with a numeric parser.
Empty fields are treated as null values.

Upload the CSV File into DeviceHub

Go to DeviceHub > Tags.
Click the at the upper right of the Tags window.
Select Upload CSV.
Select the file and click Upload.

Upon a successful upload, the tags will appear in the Tags window. If the details in the CSV file do not match the expected configuration, error messages will indicate the issues.