External Item Data Validation

This feature makes it possible to perform various data validations of data values on APIS external items before making use of the data. An alarm is triggered when a data validation fails. The alarm will be logged in the system log, but it is also possible to send it out as an e-mail notification. When a validation fails, the invalid data may be substituted according to different rules.

The data-validation is performed when the value of the item connected as the external item changes. When an item fails a data-validation check, the quality of the item will include some APIS specific quality information, see APIS Vendor Specific Item Qualities for details.

Data-validation methods

APIS supports the following data validation methods:

Data validation method Abbreviation Value1 Description Related item attribute(s)
None None / 0 0    
Bad quality BQ / 1 1 Validation fails when the quality of the item becomes bad  
Range R / 2 Validation fails when the value of the item violates a range check DvHiRange, DvLoRange
Rate of change ROC 4 Validation fails when the value of the item changes to fast DvMaxRoc
Watchdog WD 8 Validation fails when the value of the item stops updating DvWdTime
Difference DF 16 Validation fails when the difference of the value of the item compared to the value of an other item is too big DvCompareValue, DvCompareItem
Absolute difference ADF 32 Validation fails when the absolute value of the difference of the value of the item compared to the value of an other item is too big DvCompareValue,
DvCompareItem
SPC SPC 64 Any of the supported SPC tests, Apis Online SPC DvSPCTest, DvSPCLCL, DvSPCUCL

1 When using File-add, the values of the desired DV methods must be OR'ed together. Eg: R | ROC = 6

The following item attributes are used in data validation:

ID Name Description Type
5670 DvMethod The method that decides which data validation tests to use.
Any combination the following is possible:

None, BQ, R, ROC, WD, DF, ADF, SPC.		 2 byte unsigned integer
5672 DvHiRange The high limit for DV range check. 8 byte real
5673 DvLoRange The low limit for DV range check. 8 byte real
5674 DvMaxRoc The maximum rate of change for DV rate of change check. 8 byte real
5676 DvWdTime The time limit in seconds for DV watch dog check. 8 byte real
5677 DvCompareItem An external item used by data-validation methods DF and/or ADF, when comparing values.  
5678 DvCompareValue The value to compare the difference with, when using data-validation methods DF and/or ADF 8 byte real
5680 DvSPCUCL The upper control limit in SPC. 8 byte real
5681 DvSPCLCL The lower control limit in SPC. 8 byte real
5682 DvSPCTest The assignable causes tests to perform (multiple selects possible, e.g. 1;3;4).

1 - 1BEYZA,
2 - 9BEYCENT,
3 - 6INCDEC,
4 - 14ALTUPDO,
5 - 2OF3INZA,
6 - 4OF5INZB,
7 - 15INZC,
8 - 8OUTZC.
string
5690 DvSubstMethod The method that decides which data validation substitute value to use. One of the following may be selected:

Name Meaning Value
last good Substitute with last good value when data validation fails 1
InitVal Substitute with InitVal attribute when data validation fails.* If no InitVal is associated with the item, it uses the last good value 2
AltExtItem Substitute with an alternative external item (DvAltExtItem). If no alternative external item can be obtained, it uses the last good value 3
PassThrough No substitution occurs, external item is passed through as if no validation failed 4
Follow ROC Substitute with a value that increases/decreases with a rate of change limitation according to the maximum rate of change (DvMaxRoc). 5
Default First, value is  substituted after a Follow ROC strategy, if DvMethod specifies ROC. Then, if DvMethod specifies Range, a range check validation is performed. If Range-chack fails, an AltExtItem substitution  is performed if an DvAltExtItem is specifed.

If none of the above mentioned substitution occurs, the default substitution is last good.. 		255
2 byte unsigned integer
5691 DvSubstQuality The quality to use when data validation substitution takes place. This attribute lets the user control the quality for item values when Data Validation substitution takes place, the quality can be overridden to bad, uncertain or good, by specifying the desired quality using the DvSubstQuality attribute.

The APIS Vendor specific quality bits, telling what violation is broken, will still be added to the quality.
I.e. when using Range validation, the quality of the item during a violated state is decided according to the table below, but with APIS Vendor quality range added to the quality.

Name Meaning Value
Default The quality follows the quality of the source item, with any with APIS Vendor quality violation state added to it. 255
Bad The quality is always set to bad, with any with APIS Vendor quality violation state added to it. 0
Uncertain The quality is always set to uncertain, with any with APIS Vendor quality violation state added to it. 64
Good The quality is always set to good, with any with APIS Vendor quality violation state added to it. 192
unsigned character
5692 DvAltExtItem An alternative external item to fetch a DV substitute value from. Used when 'DvSubstMethod'='AltExtItem'. string

Note:

The module property ExtItemCalculationSequence is important in data validation and transfer. It decides whether data validation or data transfer will be performed first in the external item manager.

Available values:

  • TransferBeforeValidation
  • ValidationBeforeTransfer

Data-validation alarms

Data validation will generate alarms into the Alarms & Event server of APIS, and OPC clients can retrieve these alarms over OPC UA and OPC AE. Further, data-validation alarms & events can be written to an APIS event database, configuration of this is described in Advanced Event Configuration.