Line-by-line VQT Values

For more details on how to create and configure a Dropzone Datasource, please see the Dropzone Jumpstart.

Field Content

Each row might hold up to nine different field types. Including Server, Node (Branch), ItemID (Tag name), Datatype, Value, Quality, Timestamp, Location and Property. Some fields are mandatory, others are optional. Multiple Property fields are allowed, whereas all other fields should always be supplied only once to prevent ambiguities. The service stores default values for optional fields that are not supplied. Each field represents data a real OPC item delivers as well to ensure as much compliance to regular OPC items as possible. In the following, each field is described separately. Additionally, examples are provided for each field.

Server Field

Type: Optional Description: The server column holds basic information of the pseudo-OPC item’s origin. This information is stored in the namespace database of the inmation repository just as for any regular OPC item. Additionally, this information is being referenced in the system image as well as the raw and aggregated history. Any string can be supplied in the server column. Quotation marks must not be used as string indicators. A simple example is shown below.

OPCServer123

Node Field

Type: Optional Default: Root node Description: The node (branch, in classic OPC terms) field supplies more detailed information about the item’s origin. The node is used to classify multiple OPC items of the same server into separate folders, just as in a file system. Nodes and sub-nodes must be separated by slashes (/). It is recommended to also provide a slash (/) as the first character of the string. Any string that follows these rules can be supplied in the node column. Quotation marks must not be used as string indicators. Two valid examples are shown below.

/node1/subnode1

ItemID Field

Type: Mandatory Description: The ItemID field is the main identifier (item tag name) of the imported pseudo-OPC item. The ItemID is used to differentiate between multiple items of the same node of the same server. In return, imported items that supply the same information in the server, node and ItemID column are treated as the same item. The separator used in the node field must not be used in the ItemID field again. Any string conform with this rule can be supplied in the ItemID field. Quotation marks must not be used as string indicators.

ExampleItem1 Example.Item.1
The first example only consists of basic characters. The second example is valid only if dots (".") have not been used in the node field as node-separators.

Datatype Field

Type: Optional (But highly recommended) Default: Already supplied datatype / Best guess Description: In this field the datatype of the item’s value is supplied. Only certain strings (textual codes and their numerical equivalents) are valid. The datatype can be left out if an item is updated. Is this case, the service uses the datatype that has been supplied before.

Table 1. Valid variant data types
Numerical Code Textual Code Equivalents

0

VT_EMPTY

EMPTY

1

VT_NULL

NULL

2

VT_I2

I2, SHORT

3

VT_I4

I4, LONG, INT32, INTEGER

4

VT_R4

R4, FLOAT, SINGLE

5

VT_R8

R8, REAL, DOUBLE

6

VT_CY

CY, CURRENCY

7

VT_DATE

DATE

8

VT_BSTR

BSTR

10

VT_ERROR

ERROR

11

VT_BOOL

BOOL, BOOLEAN

14

VT_DECIMAL

DECIMAL

16

VT_I1

I1, SMALLINT

17

VT_UI1

UI1, BYTE

18

VT_UI2

UI2, USHORT, WORD

19

VT_UI4

UI4, UINT32, DWORD

20

VT_I8

I8

21

VT_UI8

UI8, INT64, LONGLONG

22

VT_INT

INT

23

VT_UINT

UINT, UINT64, ULONGLONG

25

VT_HRESULT

HRESULT

72

VT_CLSID

CLSID

Value Field

Type: Mandatory Description: The value column holds the pseudo-OPC item’s value. The value is stored in the inmation repository in the process image database as well as the raw and aggregated history databases. Strings can either be supplied inside quotation marks or without quotation marks. Some examples are shown below.

1
123.456
String
true

The examples shown above are stored in the repository differently, depending on the provided data type. In case no data type has been provided, the first two values are stored as VT_R8 data types. The non-numerical items shown above are stored as VT_BSTR data types. Providing a data type is highly recommended to ensure the least overhead possible. The last value for example is stored with much less overhead, given that VT_BOOL is supplied in the data type field.

Quality Field

Type: Optional Default: GOOD (Equivalent to numerical value 192) Description: In this field the quality of the OPC value is defined. Only certain strings and the numerical equivalent are valid. A list of valid strings and their numerical equivalents is shown in the table below.

Table 2. Valid item qualities
OPC Qualities (textual) OPC Qualities (numerical)

CONFIG_ERROR

4

NOT_CONNECTED

8

DEVICE_FAILURE

12

SENSOR_FAILURE

16

LAST_KNOWN

20

COMM_FAILURE

24

OUT_OF_SERVICE

28

WAITING_FOR_INITIAL_DATA

32

UNCERTAIN

64

LAST_USABLE

68

SENSOR_CAL

80

EGU_EXCEEDED

84

SUB_NORMAL

88

GOOD

192

LOCAL_OVERRIDE

216

No Quality/No Value

255

Bad/Non Specific

0

Timestamp Field

Type: Optional Default: Current UTC Time Description: The timestamp links an OPC item’s value to a specific time. Depending on the chosen import folder, different timestamp formats are expected. In the following all possible variations are explained.

Files that are moved into the "inmation.root\drop\as_opc_da_utc\" folder are expected to provide UTC timestamps. The timestamp must be supplied in a combined date and time UTC format according to ISO 8601: "yyyy-MM-ddTHH:mm:ss.SSSZ". Examples of valid timestamps are shown below.

2012-12-31T23:59:59.999Z
2013-01-01T00:00:00.000Z
2013-01-01T00:00:00.001Z

Files that are moved into the "inmation.root\drop\as_opc_da_local\" folder are expected to provide local timestamps. The timestamp must be supplied in one of two valid formats. Examples of both formats are shown below. Local Central European Time (CET) is used in all examples.

Option 1

The time offset from UTC is specified in the timestamp. The offset is being used by the service to respectively determine the UTC time. In this case the timestamp must be supplied in the following format: yyyy-MM-ddThh:mm:ss.SSS±hh:mm

2012-12-31T22:59:59.999+01:00
2012-12-31T23:00:00.000+01:00
2012-12-31T23:00:00.001+01:00
Option 2

The time offset from UTC is not specified in the timestamp. The offset is being recognized by the service automatically according to the system time. In this case the timestamp must be supplied in the following format: yyyy-MM-ddThh:mm:ss.SSS

2012-12-31T22:59:59.999
2012-12-31T23:00:00.000
2012-12-31T23:00:00.001
All examples result in equivalent timestamps stored in the repository, given that the time offset is set correctly (Option 1) and the system time is set correctly (Option 2). However, it is recommended to import files with UTC timestamps whenever possible to clear out all ambiguities from the beginning.

Location Field

Type: Optional Default: longitude: 0 latitude: 0, altitude: 0 Description: The location links an OPC item’s value to a specific geographic location. Up to four distinct values might be stored within the location field. All values need to be separated with white-spaces. The first three values must be numerical values and dots must be used as decimal marks. The first numerical value is always interpreted as longitude, the second value as latitude. The third value is interpreted as the altitude. In case only two values are listed in the location column, the service recognizes that only longitude and latitude have been supplied. In case a fourth value is provided it is recognized as the location name (location identifier). It must only be supplied in combination with three numerical values. Therefore, the location name can not be supplied with longitude and latitude only. Additionally the location name can contain white-spaces. Though, in case white-spaces are used in the location name it must be supplied within quotes. Different examples of valid location field variations are provided below.

27.988257 86.925145 27.988257 86.925145 0 Mount Everest 27.988257 86.925145 8848.00 27.988257 86.925145 8848.00 Mount Everest
27.988257 86.925145 8848.00 "Mount Everest"

The examples above link an OPC item’s value to a specific location with an approximate accuracy of one centimeter. As mentioned above the location name can only be supplied together with longitude latitude and altitude. In case a whitespace character is used, the location name must be provided within quotes.

Property Fields

Type: Optional Default: Empty Description: Regular OPC items have a variety of properties. Multiple property fields can be provided in order to import a full set of properties. Each property field must follow a certain formatting consisting of label, property ID and the property value.

  • Label: property, prop, prp, p, …

Any abbreviation with a matching first character is valid. Capitalization is not relevant.

  • PropertyID: (100), [101], {EU_UNITS}, <DESCRIPTION>, …

All of the four different brackets used above are valid. Both, textual or numerical propertyIDs are valid as well. The first and the second pair shown above are therefore equivalent.

  • Property Value: =123.456, ="Any String Value", =true, …

Each value must begin with an equals sign. String values containing a space must be indicated by quotation marks. The datatype of the property value is recognized automatically.

Several examples are shown below. The examples only use the abbreviated label and textual propertyIDs in round brackets. Though, any of the above described variations would work the same.

prop(DESCRIPTION)="Capacity" prop(LOW_EU)=0 prop(HIGH_EU)=100 prop(EU_UNITS)="%"

In the following table all valid textual and numerical property IDs are shown.

Table 3. Valid item properties
OPC Properties (textual) OPC Properties (numerical)

DATATYPE

1

VALUE

2

QUALITY

3

TIMESTAMP

4

ACCESS_RIGHTS

5

SCAN_RATE

6

EU_TYPE

7

EU_INFO

8

EU_UNITS

100

DESCRIPTION

101

HIGH_EU

102

LOW_EU

103

HIGH_IR

104

LOW_IR

105

CLOSE_LABEL

106

OPEN_LABEL

107

TIMEZONE

108

DEFAULT_DISPLAY

200

CURRENT_FOREGROUND_COLOR

201

CURRENT_BACKGROUND_COLOR

202

CURRENT_BLINK

203

BMP_FILE

204

SOUND_FILE

205

HTML_FILE

206

AVI_FILE

207

CONDITION_STATUS

300

ALARM_QUICK_HELP

301

ALARM_AREA_LIST

302

PRIMARY_ALARM_AREA

303

CONDITION_LOGIC

304

LIMIT_EXCEEDED

305

DEADBAND

306

HIHI_LIMIT

307

HI_LIMIT

308

LO_LIMIT

309

LOLO_LIMIT

310

CHANGE_RATE_LIMIT

311

DEVIATION_LIMIT

312

SOUND_FILE_AMBIGIOUS

313

TYPE_SYSTEM_ID

600

DICTIONARY_ID

601

TYPE_ID

602

DICTIONARY

603

TYPE_DESCRIPTION

604

CONSISTENCY_WINDOW

605

WRITE_BEHAVIOR

606

UNCONVERTED_ITEM_ID

607

UNFILTERED_ITEM_ID

608

DATA_FILTER_VALUE

609

It is highly recommended to supply [EU_DESCRIPTION], [EU_LOW], [EU_HIGH] and [EU_UNIT] for each item, because these properties provide client-side functionality. On the other hand it is not recommended to supply [DATATYPE], [VALUE], [QUALITY] and [TIMESTAMP] for any item, because these properties are already covered within distinct fields. This would lead to redundant data to be stored in the repository.

Field Format

Different types of field formats are supported by inmation to allow as much diversity as possible. Each row in the dataset of the file is treated as an own item. Therefore a file with n rows must hold data about n items. To allow imports to be fully compliant with a regular OPC item the importing routine accepts nine different types of fields. Semicolons as well as tabs can be used as separators. A single file must not contain different separators at the same time. Multiple Property fields are allowed, whereas all other fields should always be supplied only once to prevent ambiguities. Two different types of column formats are supported and described below. Both methods are equivalent and result in the same item structure to be stored in the repository. inmation recognizes the format type as well as the separator automatically. In the following table an overview of all possible data columns is shown.

Table 4. Dropzone text import column overview
Column Name Order Label Description

server

1

server, srv, s

name of the OPC server

node (branch)

2

node, nd, n

name of the OPC item node

itemID (name)

3

itemid, id, i

OPC item tag identifier

datatype

4

datatype, dt, d

datatype of OPC item value

value

5

value, val, v

OPC item value

quality

6

quality, qty, q

OPC item quality

timestamp

7

timestamp, ts, t

OPC item timestamp

property

8

property, prp, p

OPC item properties

Order Defined Format Type

Each item’s fields can be recognized by the service based on their order. In this case each field separated by one of the two possible separators must be deployed in the exact given order. Even if one or more field is left out for one or more items this format type still requires the dataset to be consistent. This means empty field must still be transferred to leave the field format intact.

Example 1: In this example two pseudo-OPC items are specified and semicolons are used as separators between fields. All fields contain information.

MeteringStation123;FlowRates;F-123.PV;VT_R8;132.465;192;2013-01-13T14:30:00.000Z;prop(EU_UNITS)=m3/h;prop(EU_DESCRIPTION)=Flow Rate
at Transfer Point MeteringStation123;FlowRates;F-123.ST;VT_BSTR;Operating;192;2013-01-13T14:30:00.000Z;p(101)=Metering Device
Status

Example 2: In this example two pseudo-OPC items are specified and commas are used as separators. Only the minimum set of required fields are used. Empty fields must still be transferred using the order defined format type.

MeteringStation123;;F-123.PV;;132.465 MeteringStation123;;F-123.ST;;Operating

The missing branch will be assumed to be the root branch (node) of the server. The missing datatype leads to a best guess by the system (and should be avoided in general). The missing quality will always be substituted with OPC_QUALITY_GOOD (equals the numerical value 192). A missing timestamp will be substituted with the current UTC time of the Connector service host machine. In case the location is missing no information about the item’s location is stored within the repository.

In order to avoid undesired results (such as storage waste due to careful assumptions of the service) datatypes should be supplied if ever possible. If this is not the case the system will best guess as follows:

  • In case any non-numerical character is found in the string the system chooses VT_BSTR as the datatype.

  • In all other cases the system will create an item with VT_R8 data precision with one exception: If the actual import references an existing item the system will try to interpret the value according to the existing items datatype.

Label Defined Format Type

inmation can also recognize fields by their label. In case the label defined format type is used, only fields that hold actual data must be listed. Empty fields are not required. Fields must still be separated by one of the two possible separators. Labels can either be specified by their full name or any abbreviation with the matching first character. The capitalization of the label is not relevant. Compared to the order defined format type the order of the fields is arbitrary.

Example 1: In this example two pseudo-OPC items are specified using the label defines field format. Semicolons are used as separators between columns. All possible fields contain information.

server=MeteringStation123;node=FlowRates;itemid=F-123.PV;datatype=VT_R8;value=132.465;quality=192;timestamp=2013-01-13T14:30:00.000Z;prop(EU_UNITS)=m3/h;prop(EU_DESCRIPTION)=Flow Rate
at Transfer Point server=MeteringStation123;node=FlowRates;itemid=F-123.ST;datatype=VT_BSTR;value=Operating;quality=192;timestamp=2013-01-13T14:30:00.000Z;prop(101)=Metering Device
Status

Example 2: In this example two pseudo-OPC items are specified and commas are used as separators. Only the minimum set of required fields are used. In this example only the short label (= first character of full label name) is used to specify the columns.

s=MeteringStation123,i=F-123.PV,v=123.465 s=MeteringStation123,i=F-123.ST,v=Operating

Special Cases

Importing Data assigned to Objects not belonging to the Dropzone Hierarchy

Data can also be imported and added to already existing items that reside outside of the Dropzone object hierarchy. Usually - when a virtual server is specified using the 'Server' field - this virtual server is created below the Dropzone data source object in form of an 'IO-Node' object, and all node information, such as 'Node=N1/N2/N3' is creating a 'IO-Node' hierarchy below this virtual server. In this fashion, data can only be imported for items (objects) which reside below the Dropzone virtual server 'IO-Node' object. To add to items outside of the Dropzone hierarchy, you must omit the 'Server' field and point to the absolute path of the target object, using the 'Node' field. For example, if we want to import data for an existing object with the fully qualified IO-Model path '/System/Core/Connector/Energy/HourlyConsumption', we would require the following syntax:

Node=/System/Core/Connector/Energy;Item=HourlyConsumption;Datatype=VT_R8;Value=1346.8;Quality=GOOD;Timestamp=2015-06-06T12:00:00.000Z
When importing data to objects outside the Dropzone hierarchy, the full path provided in the Node field must be valid and the item field must correspond to an already existing object in the I/O model. The node hierarchy will not be created, as is the case with file imports underneath the Dropzone.
Only objects within the Dropzone’s parent Connector namespace are accessible. The system limits the access to objects outside the Connector hierarchy. For example, objects directly underneath the Core or another Connector cannot be accessed.

Importing Historical Data

Historical Data can be imported in the same fashion as actual data. In case, the imported file contains multiple historical timestamps for a given item (object) value, it will assign those values to history and fill the raw history in the inmation repository accordingly.

Importing Bad Data (Missing Values)

The Dropzone accepts the import of empty/missing/bad data. In order to import empty data, you have to specify a data type with the value 'VT_EMPTY' and omit the Value field (respectively set it to nothing, like 'Value='). Below you find examples how to import missing data. The first example imports the missing data as 'GOOD' quality, the second as 'BAD':

Server=RegControl;Node=TIC4712;Item=SP;Datatype=VT_EMPTY;Quality=GOOD;Timestamp=2015-06-06T11:00:00.000Z