Feedback Item

The Feedback item provides feedback for external writes based on separate objects. In large systems containing many layers and sub systems, it is often necessary to acknowledge and confirm that writes have taken place. The Feedback item checks that written values are the same for linked items in different parts of the system.

Use Cases

  • Checking that external writes have occurred on connected systems

Quick Configuration

For more information about configuring the Feedback item, please visit the following pages:

Object Properties

Common

Object Name

The user-modifiable object name. This name overrides the name which has been supplied by the external system. It must be unique within the collection of objects of the parent object.

Object Description

This is the user-modifiable object description. This text overrides the description which has been supplied by the external system.

System Alias

The system alias is an additional name for an object, which can be used as a shortcut for identification and has to be unique in the system.

Display Alias

Alternate label for objects to be used for easier identification in the displays.

Engineering Unit

The Engineering Unit or unit of measurement is a definite magnitude of a physical quantity, defined and adopted by convention or by law, that is used as a standard for measurement of the same physical quantity.

Decimal Places

The maximum number of decimal digits that will be displayed to the right of the decimal point.

Attachments

File attachments stored in MongoDB file store.

Usecases

Lists the usecases that apply to this object.

Feedback Information

Compound for informational data for feedback writes.

State

The current state of a feedback write.

  • Success: Feedback for the write operation has been received and was validated (Good).

  • Pending: Write feedback is pending (UncertainInitialValue).

  • Timeout: No feedback was received for the last write within the timeout period (BadTimeout).

  • No Data: No write has been issued yet (BadWaitingForInitialData).

  • Bad Arguments Missing: Some data is missing in the write value as required by the configuration (BadArgumentsMissing).

  • Bad Configuration: The item is not configured correctly, e.g. a feedback path is unbound (BadConfigurationError).

  • Bad Write: Not all values could be written to the specified targets (BadDataLost).

  • Bad Data Syntax: Invalid syntax for the write value (BadSyntaxError).

Write Count

The number of total writes to a FeedbackItem.

Successful Count

The number of total write successes of a Feedbackitem.

Failure Count

The number of total write failures of a Feedbackitem.

Feedback Configuration

Compound for configuring write feedback specific behavior.

Mode

The write mode of the FeedbackItem.

Single Write

Compound for configuring single write behavior.

Target

Target object path for feedback writes.

Feedback

Object path for write feedback confirmation.

Initialize Target

Initialize the write target on each write operation.

Initialize Feedback

Initialize the feedback target on each write operation.

Initial Type

The type of the initial value for feedback or write targets.

  • VT_EMPTY: VT_EMPTY.

  • VT_NULL: VT_NULL.

  • VT_I2: VT_I2.

  • VT_I4: VT_I4.

  • VT_R4: VT_R4.

  • VT_R8: VT_R8.

  • VT_CY: VT_CY.

  • VT_DATE: VT_DATE.

  • VT_BSTR: VT_BSTR.

  • VT_ERROR: VT_ERROR.

  • VT_BOOL: VT_BOOL.

  • VT_VARIANT: VT_VARIANT.

  • VT_UNKNOWN: VT_UNKNOWN.

  • VT_DECIMAL: VT_DECIMAL.

  • VT_I1: VT_I1.

  • VT_UI1: VT_UI1.

  • VT_UI2: VT_UI2.

  • VT_UI4: VT_UI4.

  • VT_I8: VT_I8.

  • VT_UI8: VT_UI8.

  • VT_INT: VT_INT.

  • VT_UINT: VT_UINT.

  • VT_USERDEFINED: VT_USERDEFINED.

  • VT_FILETIME: VT_FILETIME.

  • VT_BLOB: VT_BLOB.

  • VT_STORED_OBJECT: VT_STORED_OBJECT.

  • VT_BSTR_BLOB: VT_BSTR_BLOB.

Initial Value

The initial value for feedback or write targets.

Structured Write

Compound for configuring structured write behavior.

Write Table

A table specifying the targets and feedback paths for a coherent structured write.

Allow Subset

Allow a subset of targets in structured feedback writes.

External Write Options

Compound for configuration options of external writes executed as part of a feedback write.

Mode

OPC writing mode.

  • Opc Read Cache Before Write:

  • Opc Read Device Before Write:

  • Opc Read Object Before Write:

  • Opc No Read Before Write:

Pack Delay

OPC write pack delay.

Supress Audit Write

Supress OPC write audits.

Enforce DA20 Write

Enforce write as defined by the OPC DA 2.0 specification.

Time-out

The time-out in milliseconds for a write without feedback to be considered a failure.

Tolerance

The tolerance (epsilon) to be used when comparing floating point values of the original write with feedback data. If not set, a default value such that 1.0 + eps != 1.0 is used.

Absolute Tolerance

If checked, the tolerance is interpreted as an absolute value when comparing floating point values. Otherwise, the tolerance is relative to the values being compared.

Strict Type Match

If checked, the value being written and the received feedback value are required to have the same type. Otherwise, type-mismatches are allowed when comparing feedback values: single and double-precision floating point values are allowed to match and different integer types are matched if their value ranges are compatible.

Include Current Value

Include the current feedback value when comparing values.

Initial Write Delay

The delay in milliseconds between writing an initial value to the target object and writing the actual value.

Archive Options

Selection between different archive options.

Archive Selection

Select default archive of the master core or a custom set of data stores.

Storage Strategy

Summarizes the settings for historization, aggregration and forecasting for a particular ItemValue.

  • Raw History: ItemValue is stored in Raw History Collections.

  • Aggregation 1 min: ItemValue is stored in 1-minute Aggregation Record Collections.

  • Aggregation 5 min: ItemValue is stored in 5-minute Aggregation Record Collections.

  • Aggregation 10 min: ItemValue is stored in 10-minute Aggregation Record Collections.

  • Aggregation 15 min: ItemValue is stored in 15-minute Aggregation Record Collections.

  • Aggregation 1 h: ItemValue is stored in hourly Aggregation Record Collections.

  • Aggregation 1 day: ItemValue is stored in daily Aggregation Record Collections.

Persistency Timeout

When set, the persisted dynamic value is not used if it is older than the specified timeout in seconds (e.g. 86400 would be the correct setting to persist the dynamic value for a maximum of one day). If not set, no timeout is used.

Auxiliary State Management

Configurable settings for auxiliary state management.

Strategy

Specifies how auxiliary state changes are handled.

  • Inherit: Inherit the setting from the parent object. In case of no parent object, the "Persist" mode is used.

  • Persist: All object auxiliary states are indicated and persisted to the archive.

  • Volatile: Auxiliary state changes are volatile and not persisted.

  • Inhibit: Inhibit all auxiliary state changes.

Custom Options

Compound to hold various structures to customize the object and to be read and written to by Lua-Script code or external interfaces.

Custom String

A generic string buffer to be used programmatically for custom purposes.

Custom Properties

This is an extensible set of named strings which can be used programmatically for custom purposes.

Property Name

A custom property name which can be used programmatically.

Property Value

The value of the custom property which can be read and written programmatically.

Custom Tables

This is an extensible set of named tables which can be used programmatically for custom purposes.

Table Name

A custom table name which can be used programmatically.

Table Data

Handles an entire table organized in columns and rows. The data can easily (cut, copy and paste) be exchanged with table-oriented data of other software products, e.g. MS Excel.

Write Modes

Single writes

In single write mode, the FeedbackItem object will forward its own dynamic value to the configured Target object. It then observes the Feedback object for value changes and if it matches the original value the write is confirmed.

Structured writes

The structured write mode configuration allows to configure multiple write and feedback targets.

In the Write Table property, each table row contains a Target / Feedback pair made of object paths and a name for that pair. The optional Tolerance and Absolute Tolerance fields may be used to override the global configuration values for a specific pair, when doing floating point comparisons. Additional optional fields allow to control the initialization of the feedback or target object. The Init Type field specifies the data type of the initial value as the numeric coding of the VariantTypes coding group.

In this mode, a single write operation on a FeedbackItem object will result in multiple writes to the configured targets. To be able to extract the correct target values, the value being written to the FeedbackItem is required to be a JSON string, containing either an array or object as the root element.

In case of an array, the values need to be ordered according to the rows in the Write Table property. For example, writing the JSON string

[ 3, "on" ]

writes the value 3 to the first Target path in the table, and the string "on" to the second. A JSON object can be used to not rely on ordering and use the names as configured in the write table instead

{ "valve" : 3, "pump" : "on" }

The Allow Subset configuration property allows a write to omit values for certain targets. A JSON array with less elements then configured targets may be used, or a JSON object may omit named elements.

Dynamic writes

If the FeedbackItem object is configured to use dynamic writes, the complete target, feedback, and floating point precision information is specified in the write command itself, which is required to be a JSON string.

The JSON string written to the FeedbackItem object is required to contain special elements. The root element must either be an object (as specified below) or an array of such objects.

The JSON object must contain the following elements:

  • Target: A string (object path) or the numeric id of the target object.

  • Feedback: A string (object path) or the numeric id of the feedback object.

  • Value: The value to write to the target object (see Writing values with JSON).

it may optionally contain:

  • Tolerance: A floating point number to be used as a tolerance during comparison (or null).

  • ToleranceAbsolute: The boolean values true or false specifying how to use the tolerance value (or null).

  • InitFeedback: A boolean specifying if the feedback object should be initialized on each write.

  • InitTarget: A boolean specifying if the target object should be initialized on each write.

  • InitType: The name or numerical code of a coding in the VariantTypes coding group. Defaults to VT_EMPTY.

  • InitValue: A string specifying the initial value for feedback or target objects.

The example below is a dynamic write specifying two targets

[{
  "Target" : "/System/Core/Connector/OPC Datasource/valve",
  "Feedback" : "/System/Core/Connector/OPC Datasource/valve_confirmed",
  "Value" : 45.7,
  "Tolerance" : 0.001,
  "ToleranceAbsolute" : false
},{
  "Target" : "/System/Core/Connector/OPC Datasource/pump",
  "Feedback" : "/System/Core/Connector/OPC Datasource/pump_confirmed",
  "Value" : true,
  "InitFeedback" : true
}]

Writing values with JSON

Whenever JSON is used to write values (structured and dynamic write modes), the JSON root element itself can be of different JSON types:

  • null: Sets the value of the target object to "null" (empty).

  • number: Any integral or floating point number. Precision loss may occur if the JSON representation of the number exceeds the available precision of the system or target data type when writing to it.

  • string: An arbitrary string.

  • true or false: Writes a boolean value to the target object.

  • array: The JSON array is converted to an array of values if it contains values of compatible types. Compatible types are null and values of the same "natural" type, e.g. single and double precision floating point values, and integral numbers fitting into a signed 64 bit integer representation.

  • object: An object allows to specify quality and timestamp data in addition to the value. If the JSON object contains a v element, it is interpreted as the target value (using the admissible types from this list, except object). If it contains a t element of type null or number it sets the target data timestamp and if it contains a q element of type null or number it sets the target data quality.

Examples:

Set the value of target object of the "valve" item in the structured write table to null and its quality to BadOutOfService.

{ "valve" : { "v" : null, "q" : 2156724224 } }

Set the values of target items configured in structured write mode to integer and string arrays respectively, using a specific timestamp.

[
  { "v" : [ -4, null, 6 ], "t" : 1535635540 },
  { "v" : [ "one", "two" ], "t" : 1535635540 }
]

Set the values of target items configured in structured write mode to null and a floating point array, respectively (and do not specify quality or timestamp).

[
  null,
  [ -563.23, 3901.0034 ]
]

About comparing values

The values used to write to a FeedbackItem object are stored internally and used for comparison with feedback values received later in time. The result of such a comparison depends on the Tolerance and Strict Type Match configuration:

If Strict Type Match is enabled, the stored value and the received feedback value are required to have the same type (no single and double-precision floating point type mismatches, and no different integral number types). If disabled, values are compared even if they have different, but the same "natural" type. E.g. writing a 32-bit integer value of 3 and receiving a feedback value of 3 but encoded as a 64-bit integer will result in a successful comparison.

If an external client like the inmation WebAPI or a Lua script is used to write to FeedbackItem objects, it is usually preferable to disable Strict Type Match.

When using floating point numbers, comparison is typically based on some specified tolerance (conversions and rounding errors during computations may produce values with different precision). If not specified, a default relative tolerance will be used when comparing values.

If Absolute Tolerance is checked, two floating point numbers a and b with tolerance t are considered equal if:

\$|a - b| < |t|\$

otherwise, they are considered equal using a relative tolerance:

\$|a - b| < |t| * max(|a|, |b|)\$